Doxygen is a powerful system for documenting a code base based on putting documentation comments of a particular form before every function in the code base. To see how this works in practice, look at the comments starting with "//!" in src/pllegend.c and the corresponding good-looking documentation results at http://plplot.sourceforge.net/doxygen/html/pllegend_8c.html where each function argument and each function are all documented.
http://plplot.sourceforge.net/doxygen/html/ gives access to our complete code base documentation, but the result is missing detailed doxygen comments concerning the purpose of the functions and its arguments for most functions. We currently do have at least one "//!"-style comment in each of src/plctrl.c src/pllegend.c src/plot3d.c src/plpage.c src/plsym.c but all the rest of our source code in src, drivers, bindings, etc. needs doxygen documentation comments. We could do all of that work by hand, but that should not be necessary for the subset of our functions that are in our public API and therefore documented at doc/docbook/src/api.xml. We could greatly improve the above situation by transforming that file into doxygen form. Anyone here want to implement that transformation? There is already a useful perl script called doc/docbook/bin/api2swigdoc.pl to transform api.xml into a form that can be used by swig to document all public API functions and their arguments. It should be a straightforward to modify that script to transform api.xml into doxygen comment form. Once that is done, then it should also be straightforward to insert (probably by hand editing rather than by script) the resulting doxygen comment results into the correct lines in src/*.c (ignoring the places in the above files which already have doxygen comments). This change would be a huge improvement in the completeness of our current doxygen results and would encourage further doxygen commentary for functions in src, drivers, bindings, etc. which are not covered by the limited documentation in api.xml. The reason I am bringing up doxygen again, is I am using it for my new timeephem software project. That project deals with reading and interpolating the JPL ephemeris files that give the positions of all major solar system objects as a function of time from 3000 BC to 3000 AD and calculating a useful integral from those results which helps to do the necessary general relativistic transformation between Earth-based clock results to solar-system based ones (e.g., on a space craft) and vice versa. I am about ready to release a software subpackage dealing with just the ephemeris reading and interpolating code, and I have found that doxygen produces not only excellent documentation for that package in html form but also in man page form. Thus, from my really positive experiences with doxygen for that project I would strongly suggest that once our basic API is documented as above, that we turn on the man page generation by using # If the GENERATE_MAN tag is set to YES (the default) Doxygen will GENERATE_MAN = YES # The MAN_OUTPUT tag is used to specify where the man pages will be put. MAN_OUTPUT = man # The MAN_EXTENSION tag determines the extension that is added to MAN_EXTENSION = .3 # If the MAN_LINKS tag is set to YES and Doxygen generates man output, MAN_LINKS = YES in doc/Doxyfile.in. We may also want to experiment with the xml output form GENERATE_XML = YES since once you have XML, you are on your way to essentially any form of documentation (e.g., info files) that you want. But the first step is to get our complete public API into doxgen form and that requires small modifications to the perl script, doc/docbook/bin/api2swigdoc.pl. So I hope there is a volunteer willing to run with that idea. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ uberSVN's rich system and user administration capabilities and model configuration take the hassle out of deploying and managing Subversion and the tools developers use with it. Learn more about uberSVN and get a free download at: http://p.sf.net/sfu/wandisco-dev2dev _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
