Doxygen

Doxygen is a documentation system for C/C++/Fortran/Python/Java/PHP/etc. It works by parsing special comment blocks and assembling the information into nice, polished documentation.

Doxygen has the HUGE advantage of allowing code documentation through comments in the code, which are easy to add and keep up to date, rather than programmers having to labor to create stand-alone documentation that will quickly grow stale. Additionally, even without parsing comments, Doxygen still provides information about the workings of the code.

See wikipedia:Doxygen for more info. See http://www.uintah.utah.edu/trac/doxygen/classes.html for a (rather mediocre) example of what can be done.

Installing

Configuring

Doxygen didn't need any special configure options the way I installed it:

#!/bin/sh
#
# run configure
# make
# make install

./configure \
 --prefix /path/to/doxygen

Dependencies

Doxygen uses "dot", part of Graphviz visualization software, for producing diagrams. This software has a binary installer for common platforms, and is open-source. "dot" should be installed and available on the path, so when you type $ which dot you should see a location returned. Typically it's located in /usr/local/bin/dot.

Installing on Mac OS X Lion

Ran into a slew of difficulties compiling, due to invalid flags and libraries compiled with incompatible compilers.

This is due to Apple once again putting its head up its own ass by moving away from GCC and toward whatever compiler-of-the-month they think is better.

Thanks for nothing, Apple.

Using Doxygen

The Doxygen manual [1] is exhaustive, and there's no point in reproducing it here.

Doxygen works by commenting your code using special blocks. Many examples are available here: http://www.stack.nl/~dimitri/doxygen/docblocks.html

These blocks are then parsed, and output can be generated in several different formats (HTML, LaTeX, man pages, etc): http://www.stack.nl/~dimitri/doxygen/output.html

One very handy feature of Doxygen is the ability to embed LaTeX formulas into the documentation: http://www.stack.nl/~dimitri/doxygen/formulas.html

You can use "dot" to generate graphs in your documentation, as described here: http://www.stack.nl/~dimitri/doxygen/diagrams.html

For instructions on actually generating the documentation, see this page: http://www.stack.nl/~dimitri/doxygen/doxygen_usage.html

Doxygen uses a whole bunch of special tags to parse information. A complete list is here: http://www.stack.nl/~dimitri/doxygen/commands.html