Doxygen Meeting

Doxygen is a code documentation system that automatically generates nice looking documentation in a variety of formats for your code. The main place to look for help/documentation is their web site (I can't seem to access it right now, just google Doxygen and it should be the first result). I like this system because it supports a variety of languages, including Python, Fortran, and C/C++ (so you only have to learn 1 system to document all of your codes). Also, it can output to a variety of formats, most notably html and Latex.

Once you have doxygen installed, you can generate an input file using the command

$> doxygen -g

which generates a file called Doxyfile. This file lists all of the options that you can use to generate your documentation. Unfortunately, I think some of the defaults are not very good, so I'll list some key options below:

• INPUT: Set the directories in which your source files reside
• FILE_PATTERNS: Set what type of source files you want doxygen to parse
• RECURSIVE: Set this to yes so that doxygen will recursively search the input directories
• EXTRACT_ALL: Make sure to turn this on if you want doxygen to document everything. Otherwise, doxygen will only document those items for which you have special comment blocks in your code.
• REFERENCED_BY_RELATION: This is a really useful option. If you are looking at the documentation for a function, doxygen will link to all of the places which link to that function.
• OPTIMIZED_FOR_FORTRAN: Make sure to turn this option on if are using doxygen with a Fortran code

You'll probably end up setting a lot more than what is listed above, but some of the options above are useful. Once your Doxyfile is complete, simply run doxygen with:

$> doxygen Doxyfile

And you should see a directory called html which contains your html documentation.