Doxygen Magically Turns Source Code into Documentation

Few programmers enjoy writing software documentation, though the quality of their lamentations on the subject indicates that many are talented writers. Good source code documentation takes time and effort, and it's essential, so what's an overworked coder to do? Look for tools to make it easier, like the Doxygen documentation system. Doxygen generates documentation directly from source code. It supports multiple output formats, such as HTML, PDF, RTF, man pages, and LaTeX. It works out-of-the-box with C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C#, and D, and community members have written helpers for other languages such as Perl, JavaScript, Visual Basic, Object Pascal, VB.Net, and TCL.

Doxygen is not quite magical, though it comes close. To use it, you simply document your program with good comments in a form that Doxygen understands. Doxygen then parses the code and comments and transforms them into nicely formatted output files. Using comments as documentation keeps everything in one place, making life easier for hard-working coders.

Doxygen also has the ability to extract the code structure from uncommented source code files, which is a wonderful thing when you're trying to understand strange code (including your own).  Doxygen understands the code; it is much more than just a another set of formatting tags.

Let's roll up our sleeves and use a simple example C file to show how Doxygen works. It is traditional for beginning developers to start by creating a "Hello, World!" program, and who are we to break tradition? Create a directory to store your project files and save this code as hello.c:

/**
 * @brief  Brief description: no more than one line
 *
 * This is the longer description. There must be a blank line separating
 * the brief comment from the longer description.
 */

/**
 * @file   hello.c
 * @author Carla Schroder
 * @date   July 22, 2011
.*/

#include <stdio.h>

/**
* This is a demo comment, which can ramble on for as long
* as you like
*/

void main()
{
    printf("Hello World");
}

Open a terminal and navigate to your Doxygen test directory, and then run the command doxygen -g to create a template configuration file named Doxyfile in the current directory. Open this file and make the following changes:

PROJECT_NAME = Hello World!
PROJECT_NUMBER = 1.0
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
SOURCE_BROWSER = YES
GENERATE_MAN = YES

Save your changes and then run the command doxygen Doxyfile. This should create three new directories: html, latex, and man. Open html/index.html in a web browser and admire your work. You should see something like Figure 1.


Figure 1: Your first Doxygen project - click to enlarge

There's your project name and version, and a Search bar. (Just for fun search for hello. It works, and you get a clickable link.) Next, click on the Files tab. hello.c should be listed there with the brief description and a link to the source code. Click hello.c, and you'll see a nice complete reference page like Figure 2.


Figure 2: The hello.c file reference page - click to enlarge

See how much work Doxygen does for you? It creates nice formatting and hyperlinks galore, so you can find anything from anywhere. With that single command Doxygen also created LaTeX source files and a man page, which you can read with man [filename], or in this example man man/man3/hello.c.3. As you can see from Figure 3 the automatically created page needs some work to become a useful man page, but Doxygen provides the correct formatting and man page structure to work with.


Figure 3: The hello.c man page created by Doxygen - click to enlarge

As you can see in the example, plain text comments don't need anything special other than being inside the comment blocks. The words prepended with the at-sign, @, are special Doxygen commands. In classic Doxygen fashion there is more than one way to indicate a special command, and that is with either @ or \, so both @brief and \brief are correct. Special commands are documented in the Doxygen manual.



One thing that may not be apparent from our brief example is that you can't just stick comment blocks wherever you feel like. They belong in front of the declaration or definition of a file, class, or namespace, or either before or after one of its members. Inline comments are supported only for members and parameters, and can be as long as you like, spanning multiple lines if necessary:

void function1();   /**< wise comment*/
int somevalue;    /**< long-winded comment that goes on and on
               spanning several lines
               and thankfully, finally ends*/

You can also add formatting to your comments. For instance, \a italicizes a single following letter:

int \a x and int \a y take precedence

The x and y are then italicized, as int x and int y take precedence. \b is bold, \code and \endcode begin and end a C/C++ code block, \e italicizes a whole word, and \verbatim and \endverbatim disables all commands inside the block so it will render as plain literal text in HTML and LaTeX.

Commenting Styles

Doxygen supports several commenting styles. The style in hello.c is JavaDoc, which looks like this:

/**
 * Your text or special Doxygen commands go here. You don't have to use
 * an asterisk to start every line; only the opening and closing slashes and
 * asterisks are required
 */

Qt style is also supported:

/*!
 *  Excellent comment here
 */

Doxygen supports several others, which you can find in the good Doxygen manual. If you get bored using a particular commenting style you can mix them up. Python and VDL have their own special styles. If you're wondering why use Doxygen for Python when Python has the excellent PyDoc, there are several reasons. You might be working on a mixed project that incorporates Python and other languages, your organization might have standardized on Doxygen for all projects, or you just might prefer Doxygen.

Though Doxygen seems simple, it does require some thought on the part of developers. The Doxygen manual cautions about some constraints that trip up many a new Doxygen user: to document a member of a C++ class, you must also document the class itself. The same holds for namespaces. to document global objects, such as functions, typedefs, enum, and macros, you must first document the file in which they are defined. That simply means including a /*! \file */ or /** @file */ line in the file.

Tree View and GUI

Figure 4 shows a simple treeview example using two C++ classes. To enable the treeview, set GENERATE_TREEVIEW = YES in your Doxyfile.


Figure 4: A simple treeview example that also shows what the class index looks like - click to enlarge

Figure 5 shows the Doxygen graphical interface, doxywizard. This is a nice alternative to editing the Doxyfile directly, as it shows the default settings in black and your changes in red, and organizes the options sensibly. You can see from this that you don't have to use the default Doxyfile name, but can give your file any name you want, specify source and output directories, change your HTML headers and footers, and many other options.


Figure 5: The graphical Doxywizard is a helpful configuration tool - click to enlarge

Doxygen can do much more, such as auto-generate graphs and diagrams, highlight syntax, and reference external documents. It runs on Linux, Mac OS X, and Windows. Give it a try and see what it can do for your code.

Follow @openlogic
Follow @CloudSwing

This work is licensed under a Creative Commons Attribution 3.0 Unported License
.Follow @openlogic
Follow @OSCloudServices

This work is licensed under a Creative Commons Attribution 3.0 Unported License
.