Date: Mon, 8 Apr 2002 15:35:49 -0400 From: The Anarcat <anarcat@anarcat.dyndns.org> To: libh@freebsd.org Subject: code documentation systems (phases [2-4]) Message-ID: <20020408193547.GA279@lenny.anarcat.dyndns.org>
next in thread | raw e-mail | index | archive | help
--NzB8fVQJ5HfG6fxh Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat Apr 06, 2002 at 12:49:23PM -0500, The Anarcat wrote: > [1] listing of possible systems > [2] testing > [3] choosing the system > [4] documenting libh I guess it was all much more simple that I expected, doxygen taking up the challenge much easier than planned. So this is not only [2] testing, but also [3] choosing and [4] documenting. See below. But let's start with the beginning. [2]: testing various possibilities Here here my test results. > 1- ccdoc: Extracting comments from C++ source and generating HTML [ran on `find libh/include -iname "*.h*"`] While small and looking pretty efficient, ccdoc can't handle libh out of the box. First, it can't recursively inspect directories and given input files `find include/ -iname "*.h*"` just makes too many warnings and ccdoc aborts. Second, I'm not sure it would handle the different locations for the header vs .cc files. It supports Javadoc style comments, though. =20 > 2- cxref: C program cross-referencing & documentation tool Skipped for lack of C++ support. =20 > 3- doc++: Javadoc style C++ documentatation system [ran on `find libh/include -iname "*.h*"`] Seems to run smoothly, but needs an additional command to convert source files to doc++'s format since doc++ doesn't parse the language's constructs. There's also the problem of the use of java plugins in the HTML display, which I haven't been able to test yet because I can't compile jdk1.3. Supports javadoc comments. =20 > 4- doxygen: A documentation system for C and C++ [ran on doxygen dox.cfg, a custom config file] A heavyweight but extremely powerful. Configuration controlled by a configuration file which would need to be checked in libh's CVS. Took a long time to run on the clean libh dir, but documented each class it met, with crossreferences and graphical analysis of classes relationships. Each class that had /** */ or /*! */ style comments was commented using these comments, which is none for now. Also handled *all* of libh's files gracefully (which includes files in lib/!). Very interesting piece of software. Note that it took forever to compile on my Duron 1Gz w/ 128Mb ram. Supports javadoc. > 5- understand_c: Understand can parse a C/C++ project helping reverse=20 > engineer it Could be used as a documentation system after all. But it requires a license to use it passed the 15-days eval license, which is a major problem here. Could still be used as a project browser. > 6- scandoc: A C/C++ documentation generator [ran on `find libh/include -iname "*.h*"`] Perl script. HTML produced using an template. Seems to loop forever on include/tcl/TclLanguageInterface.hh Generates doc only for tagged (/** */) classes. Generates broken doc on mozilla 0.9.9: frames don't work, ie clicking on a link on the left sides doesn't make anything showup on the right side; what looks like dot images are broken links, etc. No graphical representation support. Seems to supports Javadoc-style comments too. =20 > 7- robodoc: Code reference program similar to cxref that produces HTML Needs a very particular language to use in comments, similar to a formatted man page. Doesn't seem to generate graphs. Processes one file at a time. Doesn't seem to generate anything if non-conformant language is used in comments. Therefore probably not compatible with javadoc-style comments. Tcl support not tested, but TCL is not really our concern in libh architecture, right now. > 8- synopsis: http://synopsis.sourceforge.net/ not tested because of lack of freebsd port. [3]: choosing the documentation system Overall, I think only doxygen really did scale up to libh's complexity and problems (apart maybe from understand_c which has license problems). Doxygen could be the system of choice then, unless somehow strongly disagrees. Note that choosing doxygen doesn't keep people from using other tools (except maybe robodoc) to document the code, since most tools can recognize javadoc-style comments. Choosing doxygen merely means that I'll setup doxygen(1) as the documentatino system in doc/Makefile. I'll probably commit the doxygen(1) config file I'm using to libh/doc pretty soon. BTW, doxygen allows stylesheets in the output, so we could make its output totally freebsd-www compliant. [4]: documenting libh here comes the hardest part, after all. Note that libh's code is still pretty well documented, at least a lot of classes have already comments embeded in them. We just need to convert those to a readable format. I suggest using javadoc style format for wider compatibility. Most tools can read this format and choosing any other would restrict us to the use of a single package, without bringing any significant advantage. I've already started to convert the already existing class comments to javadoc style and I will do a mass commit of these changes soon. In the meantime, if: - you stumble upon an uncommented class and you think you figured out what it does or;=20 - you found a bad comment or; - you change whatever comment around and you think it could be a good addition to the doc, please convert the given comment to javadoc-style. This means delimiting comments using: /** * short descr. *=20 * long descr. */ or /// short descr. long descr. and also using @tags. A basic howto document the code with doxygen is available in doxygen's manual: http://www.stack.nl/~dimitri/doxygen/docblocks.html#docblocks A complete listing of doxygen's supported tags is: http://www.stack.nl/~dimitri/doxygen/commands.html (note that the devel/doxygen port also installs these bits). But please restrict yourself to use of javadoc-supported tags: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#tag since we don't want to commit ourselves exclusively to doxygen's syntax. A. --=20 Stop the bombings. Stop the murders. Anti-war. --NzB8fVQJ5HfG6fxh Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (FreeBSD) Comment: For info see http://www.gnupg.org iEUEARECAAYFAjyx8RMACgkQttcWHAnWiGdqxwCVG9yN//p+VX69hqnKIDj0gcxY dgCeJTGSIulC6GdkeG3PFy9019Eloxo= =tGzY -----END PGP SIGNATURE----- --NzB8fVQJ5HfG6fxh-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-libh" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020408193547.GA279>