The UPL Introduction to Doxygen

Chris Olsen

Introduction

What is Doxygen?

Doxygen is an automated code documentation system for use with C, C++ and Java. Doxygen can output documentation in a variety of useful formats, including: HTML, RTF, Latex and Man Pages.

Why do we need it?

Doxygen is very useful for maintaining an understanding of your own larger projects as well as useful documentation for others who use your code.

Who uses it?

John Bethencourt, Matthew Hammer and Chris Olsen, as well as many other projects and developers. You should too.

Concepts

Configuration

For each project you make that uses Doxygen, you must create a configuration file. The configuration file contains all information about how and what Doxygen will comment. A well documented Doxygen config file can be found at http://www.upl.cs.wisc.edu/tutorials/doxygen/

Some of the more important settings are:

PROJECT_NAME = ``Your Project''
the name of your project

OUTPUT_DIRECTORY = ``/home/username/public_html/doc/''
the directory doxygen will output it's documentation

INPUT = ``src/''
tells doxygen where to look for your source code

RECURSIVE = YES
tells doxygen to go into subdirectories to find source code

Doxygen must also be told what to output to.  For example, if you
wanted HTML output:

GENERATE_HTML = YES
tells Doxygen to output to html

HTML_OUTPUT = html/
tells Doxygen where to put html documentation, relative to
OUTPUT_DIRECTORY

HTML_FILE_EXTENSION = .html
tells what the extension of the html files should be (.htm or .html)

a header and footer for each page can also be set with the HTML_HEADER
and HTML_FOOTER options

There are similar options for RTF, Latex and Man Pages.

Documenting Your Code

Doxygen derives documentation from comments of two basic forms.
/**  */ and ///.  Doxygen documents whatever immediately follows the
doxygen comment.

/**
 * Class documentation appears here
 */
class SomeClass
{
  /// varaible Documentation
  int var;

  /** Documenting Method1 */
  void Method1();

  /// Documenting Method2
  void Method2();
};


In some cases it may be desirable to put documentation after an item,
in which case you can use the commenting form /**< */ and ///<.

/**
 * Class documentation appears here
 */
class SomeClass
{
  int var;         ///< variable documentation after
  void Method1();  /**< Documenting Method1 after */
  void Method2();  ///< Documenting Method2 after
};

There are a variety of commands that can be used within these special
comment blocks.  Doxygen commands are preceeded by either a \ or an @
(either is fine).  Some of the more common ones are:

param
return
author
date
file

Special commands for method documentation can be used as follows:

/**
 * Takes an integer and squares it
 * \param a The integer to be squared
 * \return The integer squared
 */
int square(int a);



Commands used for documentation of a file:

/**
 * \file someFile.h
 * \author Some Guy
 * \date 2-26-04
 */


There are a variety of other useful commands and formatting options,
check out the Doxygen website for more information.

Running Doxygen

To run doxygen just use the command doxygen followed by your
configuration file

doxygen project.cfg

Doxygen will generate documentation and output to the directory
specified in the config file.

Other Resources

This handout, an example Doxygen configuration file and example
Doxygen output is available online at
http://www.upl.cs.wisc.edu/tutorials/doxygen/ 

The Official Doxygen website is http://www.doxygen.org/
You can find information on all doxygen commands, commenting styles,
and configuration options there.