Hi, You may have misunderstood my post. The point of the test I did, was that I did NOT use a second version of the source-code. I commented the sourcecode in the same way you and Martin recommended, and let Doxygen produce the docs from the original commented dynapi code. so the question is, is documentation that looks like this:
http://www.your-site.com/~rinfo//examples/apiNew/dynapi_8js.html In a usable format or not. (Bear in mind that I tried every available command, so the output is not particularly logical - this was a test.) Let me first clear up one confusion. Doxygen DOES work with javascript, it recognizes a set list of commands, these are the commands that Martin was suggesting, using the @ before them. It does not do the more complicated work it would with c++ or Java source. You see in the above test, what the output looks like - if you feel this is not sufficient, or you would rather do a better job by hand, - fine. If you think the output approximates what we want, I will post the list of commands that doxygen currently recognizes, and integrate them into your commenting-style procedure. There's not much difference, this is an example of the commenting I used: /** @class DynAPIObject * Constructor - A static top level object required for all DynAPI related functions * * The "DynAPI" object is the top level object in the DynAPI * library.\n It is used primarily as a way to organize miscellaneous * variables, and generic functions, and to attach single instance * objects (such as DynLayer, DynDocument etc.). * Every graphical component branches off from the DynAPI object. For example, the * main browser document is referenced as a DynDocument that is a * property of the DynAPI object (DynAPI.document). All DynLayers * that are in that document are in a collection underneath * DynAPI.document.children[] and so on. * * All DynAPI methods can be accessed like: * @code * DynAPI.addPackage("dynapi.api"); * @endcode * @param none This object takes no parameters. * @deprecated this is where we comment that something is depreciated */ Doxygen is an opensource project, so if we need tweaking, that shouldn't be a problem. If you'd rather work out the documentation structure and setup by your self, and have people participate when you've got it started, let me know, and I'll get on with other things in the meantime. Cheers, Richard. ----- Original Message ----- From: "Laszlo Teglas" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Wednesday, November 21, 2001 5:01 PM Subject: RE: [Dynapi-Dev] documentation > >I presume it's a little quite around the documentation topic because > >everyone's busy writing the docs :o) > > Accually I have been coding the documentation structure as I have originally > outlined with the different modules (intro, reference, examples, tuturials). > I don't have enough coded to provide a glimps yet, but as soon as I do > (hopefully after the weekend) I will zip it up and distribute it for review. > The first draft will be just a plain jane no bells or whistles structural > prototype. > > >I don't think it's feasible to update two versions of our source-code, and > >to be honest, the docs generated from the Java version of our source code > >did not actually help me understand the DynAPI, because I'm not so familiar > >with the Java syntax. > > So my fear has been realized. I have not played with Doxygen yet, but from > what you have been able to produce from it, it does not seem promising. It > might be more trouble than it's worth. If we have to have dual source, one > in JS and one in Java, we might as well just have it in JS and cut and paste > the comments into the docs, for now. Later we could create a pearl script to > create the docs from our JS files. > > Instead of comming up with a strict language specification for our DynAPI, > it might be easier to just declare blocks of code in our comments as a > constructor for example: > > /**Constructor > This constructor instantiates widget x > */ > WidgetX.prototype = new DynLayer(); > > Than we can create a perl program that creates the docs, from these > declarations. It would look for things like '/**Constructor' and produce > <XHTML>. > > But this is a secondary project, that will only help us with automating the > reference module of our docs. For now we can just create the doc strucure > (which I started) and comment the src. > > To comment the src, we need a commenting standard, and we should try to > accomodate our future Perl Automator. (If we agree to go this route) > What types of blocks do we want to identify? (ie Cosntructor, Public > Methods, Private Methods, etc.) > > Some standards I think we should have: > 1) The first line of comment for a script block will be the declaration: > '/**Constructor' No space between /** and the declaration > 2) Following the declaration line would be the description of the code > block: > 'This constructor instantiates widget x' > 3) Following the description would be the comment closer token on a new line > '*/' > 4a) The very next line would be the function or property > 'WidgetX.prototype = new DynLayer();' > 4b) alternatly we could recreate the function in a simplied version as part > of the comment. ie instead of using the actual code for the document: > DynLayer.prototype.getClip=function() { > we could create a simple version as part of the comment: > getClip() > and use it as part of the documentation. This would make the document more > readable > > NanoFace =;^) > > > > -----Original Message----- > From: [EMAIL PROTECTED] > [mailto:[EMAIL PROTECTED]]On Behalf Of Richard > Bennett > Sent: November 21, 2001 9:29 AM > To: [EMAIL PROTECTED] > Subject: [Dynapi-Dev] documentation > > > hi, > I presume it's a little quite around the documentation topic because > everyone's busy writing the docs :o) > > I did some testing on Doxygen. > I don't think it's feasible to update two versions of our source-code, and > to be honest, the docs generated from the Java version of our source code > did not actually help me understand the DynAPI, because I'm not so familiar > with the Java syntax. > So I did a test to see if we could us Doxygen to create documentation from > our standard commented source-code. > For those wanting constructor/destructor and Java::syntax it might be > disappointing, to me it looks readable for Javascript coders. > I just did the DynObject part of dynapi.js, and I tried all Doxygen syntax > that we could use, so not all comments are genuine - some are simply to test > the output. > I did 3 manual edits to create this, all the rest is done automatically. > Have a look at this: > > http://www.richardinfo.com/examples/apiNew/ > > or if the redirect is slow: > http://www.your-site.com/~rinfo//examples/apiNew/ > > > This is the frames version, the same code can be used without frames, using > the page-top menu: > > http://www.your-site.com/~rinfo//examples/apiNew/main.html > > the two main sections are the source code: > http://www.your-site.com/~rinfo//examples/apiNew/dynapi_8js-source.html > > and the documentation: > http://www.your-site.com/~rinfo//examples/apiNew/dynapi_8js.html > > What I want to know is, if this looks like it could be of use to people > learning the DynAPI source code, if so, I'll write some documentation on > using Doxygen with DynAPI, so the commenting can be done in the same style, > by various list members. > If not, then I think we'd best simply comment the dynapi source-code > clearly, and use that as documentation. > > Some feedback on this would be great... > > Cheers, > Richard. > > > > > _______________________________________________ > Dynapi-Dev mailing list > [EMAIL PROTECTED] > http://www.mail-archive.com/[email protected]/ > > > _______________________________________________ > Dynapi-Dev mailing list > [EMAIL PROTECTED] > http://www.mail-archive.com/[email protected]/ > _______________________________________________ Dynapi-Dev mailing list [EMAIL PROTECTED] http://www.mail-archive.com/[email protected]/
