Doxygen
From charlesreid1
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.
Contents
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