Doxygen Reference
-----------------

Doxygen is a tool that generates documentation for your code based on
comments in the source, similar to Javadoc for Java. Running Doxygen
should be very simple. If you're including
$G/lib/Make.gfxtools.rules, everything should already work on a
CS dept linux machine. Just run "make doc". This will give you a
directory called doc/. Within that will be two subdirectories, html/
and latex/, which contain the documentation in those formats. If you
want dvi, ps, or pdf documentation, simply run make inside the latex/
directory. To install the html docs on the website, run "make
inst-doc" from a CS department machine. (Go to
web-int/research/vis/doc/ to see all the docs that are installed.)

If you're running on your own Windows machine or at a remote site, you
need to install the doxygen program before any of this will work.
It's not a standard unix utility, but it is free.  Install its default
location under windows and the makefile should work without changes.

If you want to change any of the standard options for Doxygen, you can
put those changes in a file called Doxyfile.local in your project
directory.  Doxygen will generate documentation for code that hasn't
been commented, but to get really useful documentation, you need to
add Doxygen-style comments. Doxygen looks for comments about an
element just before the element itself. This is the case for just
about everything in your code: classes, functions, variables, and so
on. Doxygen comments use one of the following formats:


For multiline comments:
/** ... */
/*! ... */

For single line comments:
/// ...
//! ...

There are a few special tags that you can use within Doxygen
comments. Tags begin with either \ or @ (either one can be used for
any tag). Some common ones:

@author [name or list of names] specifies the author(s) of the
code. [FIXME: if you put an email address here, will it automagically
become a link?]

@date [date in any format] specifies the date on which the code was
written.

@param [parameter name] [description] is used in documentation of a
function to explain what the various parameters are for. Doxygen
expects these for each parameter in each documented function.

@pre and @post [description] are used to describe the pre- and
postconditions of a function.

@return [description] describes the return value of a function.


For more info about any of these things, see the Doxygen manual online
at www.doxygen.org/manual.html.