This website is no longer maintained. Its content may be obsolete. Please visit http://home.cern/ for current CERN information.

Doxygen HOWTO

Authors: Jakub Moscicki & Max Sang

How to generate reference manuals automatically from your code

Introduction

Doxygen is an open source tool which automatically generates the reference documentation from the source code in a variety of formats (html, latex, rtf ...). Doxygen uses a simple text configuration file to specify various options. In Anaphe the standard name for this file is config.doxygen. Other names are allowed. The main thing is that make makedoc produces a directory containing html documentation for the package. Usually you generate reference docs for each library or module in your system separately. This documentation is self-contained and in the case of HTML is also location-independent i.e. you may move the generated html directory somewhere else (e.g. to the web server) and it will work fine (all links are relative).

Home page: www.doxygen.org.

Documenting the code

Doxygen can deal with two kinds of doc string: brief and long. For classes and files you want both, but for methods the brief is more useful (in my opinion).

To document a file, put this at the top:

/**
 * \file Definitions of interfaces IA, IB and IC.
 */

For documenting a class it's best to have both brief and long comments:

/**
 * \brief Widget thread monitor (singleton)
 *
 * The %MyClass class is a singleton accessed through etc etc...
 *
 */

class MyClass {...

For documenting methods in a class use:

  /// Number of equivalent bin entries = \f$(\Sigma w)^2/\Sigma w^2\f$
  float equivalentEntries(void) const;

(note the use of LaTeX in the comments). For longer comments which go onto two lines you need to tell Doxygen explicitly that this is a brief comment, otherwise it will think it's the long one:

  /// \brief Probability that this and another histogram come from the same 
  /// parent distribution (uses default HDIFF).
  float similarityTo(const CHBookHisto& anotherHisto) const;

To put something on the main (front) page, put this somewhere sensible:

/**
 * \mainpage The Widget Package (part of %Anaphe)
 *
 * \section intro Introduction
 *
 * This is the introduction.
 *  
 * etc...
 */

To prevent a word being linked (e.g. in the CHBook package there is a class called CHBook but when I write "the basic aim of the CHBook package is..." I don't want 'CHBook' to become a link to the class definition) just put % in front of it, like this:

/**
 * \mainpage The %CHBook package is an object oriented interface to HBOOK.
 */

The config file of every package has been tweaked (Max, July 17 2002) so you don't have to worry about cross references (or any of the stuff which comes next). Just get on with making the comments Doxygen-compliant! :-)

External references - using tagfiles

If your systems is made of several libraries then quite likely some of them depend on the others. It would be nice to cross-link the documentation, so when you can jump to all external references as easily as you can for the local ones. So-called tagfiles are meant exactly for that.

Setting GENERATE_TAGFILE in the config file tells doxygen to generate a tagfile in the current directory:

GENERATE_TAGFILE     = anaphe.fml.cpp.tag

This tagile (here called anaphe.fml.cpp.tag) is a short description of the symbols defined in the reference manual which doxygen just generated.

To use a tagfile generated by others you set TAGFILES:

TAGFILES = $(ANAPHE_DOC_ROOT)/Interfaces/doc/anaphe.Interfaces.tag

In this case I use the tagfile called anaphe.Interfaces.tag which is located in the directory $(ANAPHE_DOC_ROOT)/Interfaces/doc.

So having the two above settings in my config file I get the following: I generate the tagfile anaphe.fml.cpp.tag for other libs which use my library (FML). I use tagfile anaphe.Interfaces.tag generated by the author of Interfaces package, because I use some classes from that package and I want to cross-link to their description from my reference.

Bacause the documentation is location independant, so are the tagfiles. Tagfile does not say anything where the corresponding reference manual is physically located. This gives a lot of flexibility because you specify this information as a separate step, so you can freely move around pieces of the documentation and easily changed the html references using installdox script. This script is located in the html output directory, usually html subdirectory of the one containing config file (I personally use generated_doc/html so you will see it here):

cd generated_doc/html
chmod u+x installdox
./installdox -l anaphe.Interfaces.tag@${ANAPHE_WEB_URL}/Interfaces/generated_doc/html *

The installdox command above says: make all references (links) to classes from Interfaces package point to ${ANAPHE_WEB_URL}/Interfaces/generated_doc/html (which is the URL of my project).

For the result have a look at: Introduction to FML. External links to Interfaces package are underlined.

Anaphe standards for reference documentation

Every package contains 'doc' subdirectory which contains the GNUmakefile, config file plus any extra documentation files (most of the documentation is generated form the source and header files). These files are stored in CVS and are enough to automatically generate the reference manual for the package. Automatically generated files (reference manual) are NOT stored in CVS, because they may be easily re-created.

Obligatory parts of config file:

# environment variables which must be defined
# $(ANAPHE_DOC_ROOT) - the CVS root which is used for documentation

PROJECT_NUMBER = "<i>CVS Version Information</i>$Name$$Date$"
OUTPUT_DIRECTORY     = generated_doc

Variable ANAPHE_DOC_ROOT should point to the directory (with the same structure as CVS packages directory) where needed tagfiles may be found. Tagfiles should be located in 'doc' subdirectory of the packages (together with config file).
Documentation installation scripts should depend on two variables:

set ANAPHE_WEB_DIR = /afs/cern.ch/sw/lhcxx/share/WWW/anapheweb/documentation
set ANAPHE_WEB_URL = http://anaphe.web.cern.ch/anaphe/documentation

Sample script (thru gmake target install):