CSCI 102: Doxygen Tutorial

Fig. 1: example of a Doxygen call graph

What is Doxygen?

Doxygen is a tool to convert your C++ comments into publishable HTML.  It works by extracting commentary directly from the source with the help of a special Doxygen syntax.

Installing Doxygen

TCSH

If you're using the default shell, add the following lines to the .login file in your home directory:

if (-r /auto/home-scf-06/csci102/doxygen/setup.csh) then
	source /auto/home-scf-06/csci102/doxygen/setup.csh
endif

Doxygen will be available the next time you login; alternatively, issue source ~/.login to start using it immediately.

BASH

Similarly, if you switched to the Bourne-Again Shell; append the following to your ~/.bashrc:

if [ -r /auto/home-scf-06/csci102/doxygen/setup.sh ]; then
	. /auto/home-scf-06/csci102/doxygen/setup.sh
fi

Issue . ~/.bashrc to begin using it immediately.

Using Doxygen

Prerequisites

This tutorial assumes that you have some source available to document; whether labs or homework, and be it C++ (CSCI 102), Java (CSCI 105) or C (CSCI 101).

Initialization

Run

doxygen -g

from the source directory; the -g instructs Doxygen to create a configuration file, Doxyfile, where all the build options are kept in one place.

Commenting the Source

Doxygen comments have a special form which render them visible to the interpreter; an exclamation point, namely, is inserted after the opening asterisk:

/*! \brief A chess piece
 * The abstract parent of all chess pieces. */

class ChessPiece {
  /*! Whether we've moved */
  bool bMoved;

  /*! Move to P(x, y)
   * \param x The x coördinate
   * \param y The y coördinate
   * \return Whether the move was legal */
  bool bMove(int x, int y);
}

Template, classes, variables, methods and functions may be documented.

Special Tags

Doxygen provides several tags when commenting functions to specify parameters and return variables, the most important of which are \param and \return:

/*! \brief Move a chess piece
 * Precondition: it's the owner's turn and the move is valid.
 * Postcondition: the piece will be moved.
 * \param x New x square
 * \param y New y square
 * \return Whether the move has been performed */

bool bMove(int x, int y);

A complete list of tags is available from the Doxygen manual.

Invoking Doxygen

Editing Doxyfile

After your source has been commented, you can run doxygen Doxyfile immediately to generate content; however, if you edit the Doxyfile produced during Initialization, Doxygen's output will be more useful.  Following are some important parameters:

EXTRACT_ALL = YES

Extract documentation even from those elements you haven't yet commented.

INLINE_SOURCE = YES

Extract the relevant parts of the source and associate them with your description.

HAVE_DOT = YES

Use Graphviz for class and collaboration diagrammes.

CALL_GRAPH = YES

Generate a dependency graph for functions and methods.

GENERATE_LATEX = NO

Skip generating LaTeX sources for PDF.

Executing Doxygen

Finally, run:

doxygen Doxyfile

from the source directory.  Set permissions with chmod -R 0755 html, move the html directory to ~/public_html, and the complete documentation should be available from your web browser!

Example

See a complete project documented by Doxygen.