Documenting code with doxygen

Doxygen is a powerful tool for creating reference documentation from code. This type of tool is called a documentation generator.

Doxygen can mainly create documentation from C++ sources, but it can also support other programming languages like C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, CHDL, Tcl, and D to some extent. The documentation can be created in HTML format (on-line documentation browser), LaTeX, RTF, among others.

Installing doxygen

To install the latest version of doxygen, we can get it from the doxygen repository on GitHub. For this we need to have GIT installed. To get the initial copy of the repository input the following command:

# git clone https://github.com/doxygen/doxygen.git
# cd doxygen

Then do the following:

doxygen # ./configure
doxygen # make

To force a fresh release after an earlier check-out do the following from the doxygen directory:

# make distclean
# git pull
# ./configure
# make

Finally, input:

# make install

You can optionally create the manual of doxygen in html and pdf formats by using the following commands:

# make docs
# make pdf

The manual will appear inside the HTML and pdf directories respectively.

The configuration file

To adjust the settings that doxygen will use to create the documentation, we need to edit the configuration file. One configuration file has to be created for each project that we are working on.

To create a configuration file template, input the following command from your project folder:

$ doxygen -g <config-file>

where is the name of the configuration file. If this is left black, a file named Doxyfile will be created.

The configuration file is composed of many tags which can take different values (YES/NO, names, etc.). Some of the most important tags that we should set for starting to work with doxygen are the following: (you can change the configuration file with a text editor)

INPUT = (source folder, files)    // Write the main directory where all your source files are
FILE_PATTERNS = (file extensions) // Write the file extensions to be parsed (e.g. *.cpp *.h)
RECURSIVE = YES                   // Files in subfolders will also be parsed

EXTRACT_ALL = YES                 

If EXTRACT_ALL is set to YES, doxygen assumes that all files are documented (otherwise it will only generate documentation for files that contain doxygen comment blocks)

SOURCE_BROWSER = YES              

If SOURCE_BROWSER is set to YES, doxygen generates a list of source files, including C++ files other than the main, the code itself, and cross-references

The tags PROJECT_NAME and PROJECT_NUMBER may be used to set a name and version for the project to show in the documentation.

To run doxygen and create the documentation just use the following command:

$ doxygen <config-file>

The output files will be created in separate folders named according to the format (this can be changed by modifying the configuration file).

Documenting the code

For comments to be included in the documentation, special comment blocks need to be used (Doxygen will omit regular comment blocks). Although there are many ways to start a special comment block, the most simple one is the following:

/**
 *   ...text...
 */

Special comment blocks should be placed in front of the definition/declaration of a member, class or namespace. If you have the need to put it somewhere else a structural command should be written inside the block. (http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#structuralcommands)

For making the documentation clearer, special commands are written inside the blocks. Those will organize the information to be included in the documentation file so that it will easier to read and understand.

Some of the basic commands are shown in the following examples:

/**
 * \file         example.cpp //This is structural command that should always be included.
 * \author       me
 * \date         november 2014
 * \version      1.0
 * \brief        here goes a one-line brief description
 * \details      here goes a detailed description
 * \warning      if needed
 * \copyright    if needed
*/

/**
 * \brief        This function calculates the sum of two integers.
 * \param    x   First integer
 * \param    y   Second integer
 * \return       Sum of both integers
*/
int add (int x, int y)
{
...
}

All special commands should have a backslash or an at-sign (@) before the command name.