Using Doxygen

Table of Contents

1. What is Doxygen?

Doxygen is a tool for generating formatted, browsable, and printable
documentation from specially-formatted comment blocks in source code.
This allows for developer documentation to be embedded in the files where
it is most likely to be kept complete and up-to-date.

Doxygen currently supports C, C++, Java, and IDL, using two different
styles of documentation. Output formats include HTML,
LATEX, XML, and
RTF; additional tools can be used to generate documentation in just about
any format imaginable, including hyperlinked PDF, man pages, PostScript,
compressed HTML (HTML Help), and Microsoft Word.

1.1. Other Doxygen Features

While Doxygen appears similar to Javadoc or Qt-Doc, Doxygen offers a
wealth of additional features:

  • Highly portable (available for Unix, Windows, and MacOS X).
  • Compatible with Javadoc, Qt-Doc, and KDOC.
  • Automatically recognizes and generates cross-references.
  • Can generate syntax-highlighted annotated source code.
  • Converts from HTML tags to markup in LATEX,
    RTF, or man pages.
  • Automatically generates class diagrams.
  • Organize elements into groups, with specialized documentation.
  • Include LATEX-style mathematical formulas.

1.2. Who Uses Doxygen?

A number of high-profile projects use Doxygen extensively, and have
their source documentation available online:

There are many, many more projects listed on the
"Projects that
use Doxygen
" page.
Browsing though the generated documention of various projects is the
best way to get a feel for the flexibility of and style of Doxygen output.

2. Getting Started

The Doxygen
download page

offers binaries and source distributions for the package-happy, as well
as instructions for accessing the Doxygen CVS tree. If you encounter
problems while building or installing, be sure to consult the
Doxygen
installation guide

for known problems and workarounds.

To generate documentation from your project, you’ll need a Doxygen
configuration file, usually named Doxyfile. To do this, you can
have Doxygen generate a simple, basic configuration:

doxygen -g filename

Alternatively, you can use the doxywizard tool, which provides a GUI
interface for creating and editing the configuration file. doxywizard
is included with Doxygen, but you’ll need to enable it during compilation
(if you compiled Doxygen from source) with the --with-doxywizard
flag to configure. doxywizard requires Qt 2.x to run.

A few options which I have found very useful to enable in the
configuration file are:

Option Description
EXTRACT_ALL=YES Generate documentation for all elements, even if they don’t have
documentation yet.
JAVADOC_AUTOBRIEF=YES When using Javadoc-style comments, treat the first sentence
as the brief description, and everything else as the detailed
description (this is the Javadoc standard behavior).

SOURCE_BROWSER=YES

Generate a list of source files with cross-referenced entities.
GENERATE_HTML=YES

Generate HTML documentation, including class diagrams.
GENERATE_LATEX=YES Generate LaTeX documentation. A makefile will also be generated so
that you can build PostScript, PDF, and DVI versions correctly.
RECURSIVE=YES

Recursively search from the current directory for source files.

GENERATE_TREEVIEW=YES For HTML output, generate a sidebar index.

More options can be found in the
configuration
section of the Doxygen manual
.

3. Writing Documentation

The good news is that if you already are familiar with Javadoc or Qt-Doc,
you already know the basics of writing Doxygen documentation. For those
unfamiliar with either system, the basic idea is that you place
specially-formatted comments immediately above anything you want to
document (such as a class, struct, method, field, etc.).

Javadoc-style example:

/**
* Method documentation.
* @param x The parameter.
* @return The return value.

* @see anotherFunction()
*/

/** Single-line documentation. */
/// Single-line documentation.

Qt-style example:

/*!
Method documentation.

\param x The parameter.
\return The return value.
\sa anotherFunction()
*/

/*! Single-line documentation. */
//! Single-line documentation.

In addition, Doxygen also lets you place documentation after an
element, useful for quickly documenting enums, structs, and member
variables:

int a;/// Javadoc-style.
char b;//! Qt-style.

For C and C++ files, you can place the documentation for your
elements in either the header or the main file; Doxygen will match up
declarations with the actual code.

3.1. Common Doxygen Markup

Include the following markup commands in your documentation to denote
special items. I’m using Javadoc-style here; for the most part,
the Qt-style equivalents are the same keyword, but starting with a
backslash rather than an at-symbol.

Markup Description
@param var desc...

Document a parameter called var to a function or method.

@return desc... Document the return value of a function.
@see elem Add a "see also" link to elem, which can be a function,
class, or any other documented identifier.
@author name

Indicate the author of an element.
@author name

Indicate the author of an element.
@version ver

Indicate the version of an element.
@todo desc...

Leave a note about unfinished work.
@warning desc...

Leave a warning.

See the Special
Commands Reference
for a complete list of markup commands.