Doxygen Guide

This page will show how to properly document code using specially formatted comment blocks and Doxygen.

Note: The guide is a work-in-progress. Refer to the Doxygen Manual for further information on how to use Doxygen.

Reading the Documentation

The compiled Doxygen documentation for Commander can be found at http://sdcityrobotics.org/commander_documentation/. The username and password will be given upon request.

Creating Doxygen-style Comments

To start a Doxygen-style comment, create a standard multi-line comment block on the line above whatever you are documenting, but insert an '!' after the first asterisk. So, the comment block would look something like this:

/*!
 *  Put whatever info you want here.
 */
someFunction();

It's best to include a brief summary of whatever you're documenting in the comment block, followed by a more detailed explanation. You do this by using the \brief command. For example:

/*!
 *  /brief A brief description
 *
 *  This is a more detailed description of whatever is being documented.
 *
 */
int important_variable;

Documenting Function Declarations

When documenting functions, include documentation on the parameters of the function using the \param command, if any, and what the function returns using the \return command, if any. For example:

    /*!
     * \brief A brief description
     * \param name_of_parameter This is what this parameter does
     * \return What does this function return and why
     * 
     * This is a more detailed description of whatever is being documented.
     * 
     */