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
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
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
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
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 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