Overview | CMake | Git | Documenting

This page is divided into the following sections:

Basic idea behind Doxygen

Doxygen analyzes code, searches it for special tags and generates documentation of the analyzed code according to the found tags. Doxygen was designed for languages of the C family (including C++, Java) and could be extended to other laguages of this kind.

In order to make Doxygen work with TNG one has to strictly follow some guidelines during programming.

Within the CMake build system, the target doc was introduced to compile all Doxygen parts. They consist of

Special considerations for TNG

Special care is required in order to let Doxygen generate proper documentation. Particular care requires the interaction with SWIG.

Custom commands

The following additional commands may be used in the documentation blocks:

Custom Doxygen sections

When generating a module documentation, special sections (flags) are defined which are known by Doxygen. Depending on the sections being defined one can publish custom documentation code. These code blocks can be defined using the Doxygen commands \cond, \if and \ifnot. A small example illustrates it:

//! \cond API_DOC

//! does something (only available in C++ doc)
void doSomething();

//! \endcond

//! this method is available in C++ and SWIG doc
void doSomething2();

//! \if SWIG_DOC This method is documented in SWIG doc only \endif 
void swigCode();

\brief computes a value.
\param val is the value to be set.
\brief in Lua, it returns a value.
void setAValue(double & value);

Enabled sections are

Custom preprocessor definitions

SWIG parses *.i files in order to know the header files to be generate a binding from. However, there is no easy way to let Doxygen understand SWIG input files. What can be used, is that SWIG ignores the header parts which are selected by
#ifndef SWIG

Doxygen can be configured to understand such predefines. When creating the SWIG API documentation, the preprocessor directive

#define SWIG 
will be emulated by Doxygen.

Note: Doxygen will parse all source files of a module. Therefore, source files being not parsed by SWIG must contain

#ifndef SWIG
Else it will be added to the scripting documentation, which is wrong.

Important commands

Widely used Doxygen commands found in the source files are


Generated on Thu Nov 18 00:19:51 2010 for SLangTNG by  doxygen 1.5.6