DoxygenDocumentation

Doxygen documentation

The QVision code is documented with the usual doxygen notation. Each source file (.h, .cpp) in the QVision must include the following doxygen code, so the doxygen documentation page for each source file shows the author (PARP) and a reference to the QVision:

:::c++
/// @file
/// @brief File from the QVision library.
/// @author PARP Research Group. University of Murcia, Spain.

The manual pages, and the documentation included in the API pages for the different modules are documented in ‘.dox’ files contained inside the directory ‘trunk/src/doxygen’.

The file ‘Doxyfile’ in the trunk/ directory contains the configuration to generate the doxygen documentation. The only part of that file which is likely to change is the content for the field PREDEFINED. It contains a list of pre-processor variables which doxygen assumes to be defined when parsing the source code.

Sometimes new functions should be defined in header files inside an ifdef conditional directive, for example:

:::c++
#ifdef NEW_DIRECTIVE
void testFunction();
#endif // NEW_DIRECTIVE

Doxygen parses the preprocessor directives, and can ignore trunks of code inside such conditional directives if the test variables are not defined. To avoid this, the test variable (in this case NEW_DIRECTIVE) must be included in the PREDEFINED field, so doxygen assumes that this preprocesor variable is defined, and parses the code inside the conditional directive.

The field PREDEFINED contains the variable DOXYGEN_IGNORE_THIS, so doxygen will always consider that this preprocessor variable is defined. This is why the following ifndef directive is commonly used to make doxygen ignore a part of the code. For example:

:::c++
#ifndef DOXYGEN_IGNORE_THIS
[… header code to be ignored by doxygen …]
#endif // DOXYGEN_IGNORE_THIS