Doxygen

Doxygen is an automated method of documenting code... you add a few special comments to the header files and then run the Doxygen program, which spews out about 50MB of HTML files which document the code in a web browser.

Installation

You can download the software from:

http://www.stack.nl/~dimitri/doxygen/

To generate the diagrams you'll also need GraphViz from:

http://www.graphviz.org/

And the Microsoft Help Workshop to build the help file from the HTML files:

http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&DisplayLang=en

Use

There's a sample config file in the source directory 'Doxyfile': run the Doygen Wizard program, open the config file and press 'Start' to process the source. There's also another version which produces a cut-down file, 'MiniDoxyFile': that skips the diagrams and doesn't include the source in the files.

Documenting Code

Basically, if you add a new function int DoStuff(x, y) you should put a comment before its definition in the header file like:

///
/// This is what the function does in detail.
///
/// \ingroup GroupName
/// \brief This is a brief description.
/// \param x This is what parameter x does.
/// \param y This is what parameter y does.
/// \return This is what it returns.
///
int DoStuff(x, y);


Note the use of three slashes rather than two: Doxygen only processes comments with the extra slash. Obviously if there are no parameters and no return value then you can skip that, and for variables you typically only need the brief description.

Groups are defined in nassdefs.h, and you could add new ones if you think those aren't appropriate. Look at les.h for examples if the above doesn't make sense. Also note that if you document a virtual function in a base class then that documentation is also applied to any derived classes, so you don't need to document the functions in derived classes unless they do something different.