I've never used Doxygen before. Looks very interesting, and I will read up on it. At a cursory glance, it looks handy already for a few of my open projects.

A few more notes on doxygen:

Doxygen comes with a very useful helper program called Doxywizard that allows to create a sane and well-documented Doxyfile with a few mouse clicks. Switching it to expert mode allows all kinds of fine-tuning. Plus, you can try all changes without actually changing the Doxyfile (Doxywizard feeds the configuration into doxygen from memory via STDIN).

It is very recommended to install Graphviz. It creates useful (and very impressive) call graphs, class diagrams, and much more. All from normal code with doxygen comments, without any extra work (except for the computer). Our clients are regularily impressed by the amount of source code documentation that we generate. Most of that is automatically generated by doxygen and graphviz.

We keep the Doxyfile in subversion and add a batch file or shell script named build-docs to automatically generate the documentation in HTML format in a directory docs just below the top-level directory of the project. Next to the script, we have a README.html that explains that doxygen needs to be installed, build-docs has to be started, and then links to where doxygen creates its output.

The doxygen HTML output works much better with Javascript enabled. If you open the documentation from a filesystem (i.e. via a file:// URL), a modern browser will usually disable Javascript for security reasons. You may wish to add an exception or run a tiny webserver for viewing the documentation.

Alexander