This document covers how we prefer to document our source code.  Doxygen provides a large range of options with regard to source documentation. The following document is meant as a set of guidelines to help us gain consistent layout and to help newcomers get started with Doxygen.

The latest version of the source code documentation is located at /doc and regenerated every night.

Header files

Classes should be documented in the header files and should contain a description and @class deceleration.

#ifndef _MYHEADER_H_
#define _MYHEADER_H_

/**
 * Short class description.
 * Longer, possibly spanning multiple
 * lines, description. 
 *
 * @class MyClass MyClass.h "incdir/MyClass.h"
 */
class MyClass {

public:
  MyClass();
  int Foo(int bar);

private:
  //! Description of member variable.
  int myVar;

}

Body files

Functions and methods should be documented in the body file and contain at least a description of the function, its parameters and return value.

#include "incdir/MyClass.h"

/**
 * Constructor description.
 */
MyClass::MyClass() {
  // constructor code goes here
}

/**
 * Function description.
 * Additional information about the function.
 *
 * @param bar Info about the parameter \a bar.
 * @return Info about return value.
 */
int MyClass::Foo(int bar) {
  // Foo code goes here
}

Notice the use of \a before a word to make it stand out as a special word in the documentation.

Keywords

The most useful keywords are:

@class

Class information. Syntax: ClassName [ClassHeader] ["ClassHeaderLocation"]

@param

Description of a function parameter.

@return

Description of function return value.

@see

Reference another function of class.

@todo

Note about some missing functionality.

@warning

Important notice.

@pre and @post

Function usage conditions.