We use Doxygen to generate documentation. Comments need to follow the rules to produce readable documentation. In the examples below

Comments to be parsed by Doxygen should begin with three slashes (///). Multiline comments can also use /** * /syntax (e.g. see module documentation).
Doxygen tags should begin with @
Each file has to begin with the following comment: MyClass.h.
In each module one should create file moduleName.dox that contains description of the module.
Classes, files, functions can be added to module documentation by directive @addtogroup (we recommend to add good selection of them to make documentation more readible). MyClass.h.
Each class, struct or union has to be preceded by comment: MyClass.h.
Each function definition must be preceded by a commentary of the following structure: MyClass.cpp or MyTemplate.hpp.
The second form ensures that the number and names of variables are the same in the code and in the documentation.
Note: Sections @param, @return and @exception can be ignored only if the function has no arguments, the value passed by the function is void or function does not throw any exceptions.
Comments for class members, methods should be placed directly before them using /// or just after them using ///< e.g. MyClass.h.
In comments for doxygen, you can use most of the html tags.
General documentation (e.g. of compilation process, requirements) should be placed in docs/src directory in files with .dox extension.

Code of an example was used to generate this documentation. It can be produced by invoking make doc in the capd_doc directory.

Full documentation of Doxygen can be found at http://www.stack.nl/~dimitri/doxygen/.