Doxygen

Doxygen is the central point for source documentation at this moment (January 2011).

It is a software which extracts (special) comments from sourcecode to produce source documentation.

This is done and put online on a regular basis at http://svn.gnucash.org/docs/HEAD/.

Creating the Source Documentation

It can be run on your local copy of the sources by

./configure --enable-doxygen --enable-html-docs
make doc

This will populate $BUILDDIR/src/doc. Problems will be logged there to doxygen.log. The HTML docs can be found in its subdir html.

To mark a C style comment for Doxygen, it has to start with /** or /*!.
Usually the explaining comment should be in front of a declaration. If the comment is behind a member declaration, the next symbol should be <, resulting in /**< or /*!<.
Doxygen keywords begin with \ or @.
To document global objects, you must document the file in which they are defined:

/*! \file */

or

/** @file */

A header file of a public API should have the following Doxygen section:

/**
 * @addtogroup <module>
 * @{
 * @file
 * @brief <A brief sescription>
 * @author Copyright (C) <year> <name> <email>
 */

where <module> is usually the name of the directory.