Working with Doxygen

Whenever possible, include Doxygen-compatible documentation in your code (in header files). Doxygen is a code documentation engine that builds an entire local cross-referenced set of docs.

Generate Documentation

Make sure you have Doxygen installed. If not:

$ sudo apt-get install doxygen

In order to build the documentation, navigate to the CARLsim doc folder and run:

$ doxygen CARLsim.config.doxy

This will generate the documentation in HTML format and put it in a local folder "html". Simply open "html/index.html" in your browser, and you are good to go.

The main page you see when opening "html/index.html" can be found in "interface/include/CARLsim.dox". This page should contain a concise overview of what CARLsim is and can do. It should give a big-picture description of how to use the user interface and the regression suite.

Documentation Style Guidlines

• Document each piece of code you contribute.
• Pay special attention to the documentation of the (public) user interface.
• Classes, class methods, and class members are to be documented in the corresponding header files.
• The CARLsim state(s) in which the function call is allowed should be included using the keyword \STATE (see below).
• The use of all input and output arguments should be adequately explained.
• The documentation should be structured as follows:

/*!
 * \brief A brief description of the function.
 *
 * A longer and more detailed description of the function.
 * Multiple lines are allowed.
 * A variety of tags are available, such as the following. Put the tag first (starting
 * with a backslash), 
 * followed by your comment.
 * \note Add a note if needed. 
 * \TODO Mark unfinished work with a todo tag.
 * \FIXME Mark broken stuff with a fixme tag.
 * \deprecated Deprecated functions should be marked with this.
 *
 * \STATE CONFIG, EXECUTION
 * \param[in] param1 This is the first input argument, which does this and that.
 *                   Default value: blah.
 * \param[out] param2 This is an output argument, which does this and that.
 * \returns return1 This is what the function returns
 */
return1 myFunction(int param1, float& param2);

• Private members don't need the above verbose documentation, a one-liner is sufficient:

//! This is a brief one-liner of param3
int param3;

int param4; //!< you can put the one-liner after the variable, but then
            //!< the "//!" needs a subsequent "<"