I like your suggestion with the @ symbol and * to start each line. Perhaps I can expand on your suggestion and develop a final src comment standard so we can finaly begin commenting the src.:
What every file should begin with: /** * DynAPI Distribution * The DynAPI Distribution is distributed under the terms of the GNU LGPL * license. * * @class DynLayer * @package dynapi.api * @file DynLayer.js * @version v1.71 * @date Sun Nov 11 16:25:18 2001 UTC * @inherit DynObject * @purpose The DynLayer is the standard class used to manipulate "layers". * @bug [optional keyword] any known issues * @author [optional keyword] for personal extentions */ What every function block should be preceeded with: /** * @method (public|private) | @constructor | @property (public|private) * @deprecated [optional keyword] * @syntax setClip(int top,int right,int bottom,int left) * @usage some text describing the function or property * @param top (int|sring|array|object)[optional keyword] some description text. * @param right (int|sring|array|object) [optional keyword] some description text. * @param bottom (int|sring|array|object) [optional keyword] some description text. * @param left (int|sring|array|object) [optional keyword] some description text. ... */ Do we need to add/change anything? NanoFace =;^) -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]]On Behalf Of martin ström Sent: November 21, 2001 11:34 AM To: [EMAIL PROTECTED] Subject: RE: [Dynapi-Dev] documentation Totally agree with you. two versions is one too much to maintain and since DynAPI requires some Javascript-knowledge it shouldn't be too hard to understand the Doxygen-generated docs. we could extend the documentation with own keywords, not yet supported by Doxygenm, but could be supported if we decide to make our own doc-generator (like Laszlo talked about). however it gives a good overview in the source: /** * @constructor * @inherit DynObject * @param id (optional) some description text.. * @param x (optional) some description text. * @param y (optional) some description text. * @param w (optional) some description text. * @param h (optional) some description text. ... */ function DynLayer() {...} @constructor and @param are not Doxygen commands but i think they help understanding the source. i like the javadoc- syntax, using @ before commands and start each line with * to clearly specify whats comments and whats not. /martin > -----Original Message----- > From: [EMAIL PROTECTED] > [mailto:[EMAIL PROTECTED]] On Behalf Of > Richard Bennett > Sent: den 21 november 2001 15:29 > 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/dynapi-dev@lists.sourceforge.net/ _______________________________________________ Dynapi-Dev mailing list [EMAIL PROTECTED] http://www.mail-archive.com/dynapi-dev@lists.sourceforge.net/ _______________________________________________ Dynapi-Dev mailing list [EMAIL PROTECTED] http://www.mail-archive.com/dynapi-dev@lists.sourceforge.net/
