IntroductionDoxygen is a documentation system for C++, IDL and C that runs in most of the UNIX flavors and Windows NT.
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.
See the LCG SPI doxygen page for package availability and downloads.
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
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
Single line documentation can be specified in the comment form "///"
/// Yet another method of this class.
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
This page last edited by PM on January 13, 2005.