How to use Doxygen to generate documentation

Doxygen is a useful tool to automatically generate documentation for code. It can produce beautiful documentation if the code comments are written in its custom format. Thankfully, even if this is not the case it can still produce documentation that can be useful for understanding a mass (or mess) of code.

Doxygen uses a configuration file, typically named Doxyfile, to generate documentation. Linux users might like to set their configuration in this file. Doxygen also ships with a GUI tool named Doxywizard that makes it easy to create a configuration file and generate documentation for the first time. Windows users might find it easier to use this tool.

Using Doxywizard

As an example, assume the code in a project has the following directory structure:

C:
+---Foobar
    +---Code
    +---Docs

That is the project root directory is C:\Foobar, source code directory is C:\Foobar\Code and the documentation produced by Doxygen will reside in C:\Foobar\Docs.

To produce this, fill the fields in Doxywizard as follows:

In the Run tab choose Run Doxygen to generate the documentation. It will be produced in the format you chose: HTML, CHM, XML, RTF or many others.

It is a good idea to save the configuration to a file named Doxyfile in the project directory. Do this in the Doxywizard by choosing File → Save As. By having a configuration file around, the documentation can be updated whenever the code in the project changes. This can be done directly by invoking doxygen.exe in that directory or can be automatically invoked by your build tool.

Using doxygen

The doxygen program can be used to generate a sample configuration file named Doxyfile for you:

$ doxygen -g

If you open this file, you will find that it has all the options understood by the version of doxygen on your computer. These options are excellently documented making it easy to configure them.

However, the hundreds of options in this file can be quite intimidating. I typically configure these options to start off:

• PROJECT_NAME: Give the project a name

• OUTPUT_DIRECTORY: Directory to store the generated document files. If you do not specify anything, the subdirectories are created in the current directory. For example, directories like html and latex.

• INPUT: Directories where your source files are. Strangely, they need to be separated by spaces.

• GENERATE_LATEX = NO: This option is set to YES by default. Doxygen generates HTML and Latex by default. Who needs LaTeX?

To generate documentation:

$ doxygen

To get started quickly, I have shared my Doxyfile for C++ and CUDA code here. Just look for foobar in the file and replace with your project name and directories.