Using Doxygen

Links:

    Quick Doxygen Tutorial    -   This shows how to run Doxygen and how to setup a quick and dirty config file. I won't duplicate that here, but I will write down some conventions that we should be following to use doxygen.

Conventions:

Header: Every file should contain a header comment at the very top of the file, and should look like this:

/**
 * Description for this file
 * 
 * \file myFile.h
 * \author Jermey Bell
 * \date 05-04-82
 */

Classes/Structs/enums/unions: Every one of these should be preceeded by a descriptive comment block that looks like this:

/**
 * This class does something useful, really
 */
class UsefulClass

Functions/Methods: Each one should be preceeded by a comment block that describes the function, each parameter, and the return value.
Example:

/**
 * This function does something extremely useful
 * /param usefulness A floating point value between 0.0 and 1.0 indicating the amount of usefulness required
 * /param crashiness A floating point value between 0.0 and 1.0 indicating the probability of crashing required
 * /return Returns a value between 0.0 and 1.0 that should be useful for something
 */
float Function(float usefulness, float crashiness);

Member Variables: Each member variable should have a comment preceeding it, or a comment after it in doxygen form:

/// Use three slashes to comment the next thing
float someVariable;
float someOtherVariable; ///< use three slashes and a left backet to
comment the thing preceeding this comment