Introduction

It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in ) from a set of documented source files. There is also support for generating output in RTF (MS-Word), Postscript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.

In LHCb we use it do generate the online documentation of the software. An example of the output is available here.

Installation

See the LCG SPI doxygen page for package availability and downloads.

Using Doxygen

The documentation is mainly extracted from the comments in header files. The comments are formatted  using the Qt style or the JavaDoc style.  We recommend the JavaDoc style in LHCb. An example of C++ header file and C++ source file following the LHCb recommended is available. The documentation generated from these two files can be found here.

Formatting  header files

The description of a class is placed before the class statement. Typically this a multi-line comment of the form /** .... */ The first sentence is used for the summary of the class and the rest more more detail documentation. HTML tags can be embedded in the comment special commands like @class, @author, @date are available. A full list of commands can be found in the Doxygen Manual . A simple and sufficient example is:

/** @class ClassName ClassName.h Package/ClassName.h

    The first sentence is used as a summary description by the 
    documentation tool. The description of a class is expected 
    to be found before the class declaration in the .h file. 
    The code is documented follwing the JavaDoc style. Using the multi-line 
    documentation block or the simple line documentation as is shown in this
    example.
 
    @author Author Name
    @author Another Name
    @date 20/11/2000
*/
class ClassName {
 ...
}

Each method can be documented by the comment before the method declaration. Argument and return parameters can be specified using the @return and @param commands.

/** A method example with some arguments. The arguments can be 
    documented as normal inline comments
    @return status code
    @param argument1 this is the first argument
    @param argument2 this is the second argument which goes 
    after the first argument 
*/
virtual int method2( Type1 argument1, Type2 argument2 );

Single line documentation can be specified in the comment form  "///"

/// Yet another method of this class.
StatusCode method3(); 

Setting up a main page

The entry point of a doxygen web is called the index page. This page can be customized by including the /mainpage command in a comment block. See for example the file MainPage.h that sets up the LHCbSys index page.

Generating the documentation

The doxygen application is driven by a configuration file. This file instructs from where to find the source code files and what options to enable or disable. The command to execute the application is:

> doxygen DoxyFile.cfg

Configuration files can include other configuration files, and can refer to other doxygen webs via tagfiles.

Example configuration files are those used to generate the Gaudi documentation: DoxyFile.cfg, DoxyCommon.cfg, DoxyTags.cfg. These files can get rather complex, and may use environment variables, so it can be useful to have a script to generate the documentation instead of invoking doxygen directly. For example the LHCb documentation is generated with the script $LHCBHOME/scripts/makedoc.py