NuSpatial C++ Documentation Guide

Adding documentation to your code

//* A name class
/**
* The basic class description, it does:
* 1. blah
* 2. blah ....
*
*/
class NameOneTwo
{
  public:
    /*!
    * \brief This description shows up at the top of the doxygen so you don't have to scroll.
    *
    * This description is displayed lower in the doxygen as an extended description along with
    * the above brief description.
    * \param junk       This is a cool junk varible
    */
    int MethodOne( int junk);

    /*!
    * \brief This description shows up at the top of the doxygen so you don't have to scroll.
    *
    * This description is displayed lower in the doxygen as an extended description along with
    * the above brief description.
    */
    int MethodTwo();

  private:
    int var_abc;                /**< A variable (i.e. it does something special). */
    int error_number;     /**< A variable that can be confused with the other variable. */
    string* name;           /**< A variable that is the coolest. */
}

The \todo tag

Doxygen provides a \todo tag, that can be used in any Doxygen-style comment block, e.g.:

/** @todo Make the value externally configurable */
double distance = 1.0;

Doxygen collects these tags into a "related page," providing a nice reference for remaining work. This is better than using //TODO or //FIXME or whatever other comments you might normally use, because it makes the todo-ness externally visible.

Please use the \todo tag wherever applicable.