How to document code for Doxygen

Introduction

Doxygen is a code parsing software used to create documentation for a variety of programming languages using a standardized syntax. Doxygen can be used to generate online documentation in html format or to create a reference manual in the form of a pdf postscript or latex format.

Doxygen usage:
The first step would be to make sure doxygen is installed on your unix or windows system; if not, the distributions of source code and instructions are available from http://www.stack.nl/~dimitri/doxygen/download.html The same standard for code and file fonts as in the programming guidelines tutorial: For all examples, code and file names are displayed as

html code
font

. File name example cisThisIsMyFile.h and code example int myVariable;. A Makefile is used to configure the settings of the doxygen parser which is contained in a .dxx file. To compile the doxygen generated html use the command make htm to generate html pages.

Documentation Basics

Use doxygen commenting in the .h (include) files of your code
Use the /*! sequence to indicate the start documentation blocks and */ to indicate the end of commenting. The same rules apply when ever you start a documentation block you must close it and be careful not to place source code within these documentation blocks. If one text line is sufficent for documentation use //!. Inbetween the start of a documentation block, the use of asterisks is optional at the beginning of each line.

A typical documentation block

/*!
  (doxygen comments)
  ... 
  ... 
  ... 
  
 */

These documentation blocks allow doxygen to know what to parse in order to generate the documentation.

Class documentation

Use the /*! before the declaration of a class to provide some descriptive information about the class.
Use the \brief tag to provide a short one line brief description of the class.
Use the \sa (See Also) keyword to link to related variables, methods, or classes. This is the equivalent command to \see tag. The command sets the next section to trigger a link to anything that might possibly be a keyword and also in the html document creates the phrase "See Also:" followed by the linked parameters.
Use the \ingroup to specify which group this class's documentation should be grouped under. Refer to the section on Grouping below.

/*! \brief classB: A normal class
  \ingroup common
  This class likes bob.
  This class is part of the group common.
  This class inherits class A  
  \sa classA 
 */
class classB: public classA{
...

File listing/documentation

At the top of every .h file (except for template and inline files) after the cvs header, one should place a \file tag to label the file. The syntax actually takes in a filename as a parameter and can use the \brief but for our purposes this is not required
for example one should use:

 
/*! 
  \file 
  \brief
  \ingroup tracking 
 */

For the erc libraries, the requirement is the use of \file without any arguments, \brief to give a short blurb on the purpose/contents of the file and a \ingroup with the group to which the file belongs to in order to link this file's documentation to the group. The \file listing must be used or else documentation for the #define's and the typedefs will not be used.

Grouping

Using groups for classes:

Groups are a way of organizing related classes methods into a single subunit. To define a group use the \defgroup group_name group_label syntax in the main.hpp file located in the doxygen subdirectory. This main.hpp file contains the definitions of all the groups present.
Add to this list by using the \defgroup syntax followed by a short name that doxygen will use to identify the group and optionally by a label; the name that is actually seen on the output documentation.

/*! \defgroup common CIS Common Tools    
   Documentation for cisCommon. 
 */

/*! \defgroup vectors CIS Vectors 
   Documentation for cisVecs and cisGeomObjs 
 */

/*! \defgroup tracking CIS Tracking Devices 
   Documentation for cisTracker and its derived classes. 
 */

The above is an example of what main.hpp looks like.

Inside a documentation block of a header file and use the \ingroup groupname to stipulate that the following code belongs to the group specified by the tag. This should be done in the documentation blocks of classes and functions to link them properly in the html output.
```
/*! \ingroup tracking
   \brief function to set some value
   \param a Integer value.
 */
```
An alternate method would be to use the tags \{ and \} to demarcate the beginning and end of the grouping.
```
/*! \ingroup tracking
 */

/* \{ */
....(class definition)
....
/* \} */      
```
This would result in the class defined between the \{ and \} to be part of the group tracking.

For the erc libraries, the use of the first option with the \ingroup inside the documentation block of the function or the class.

Grouping of items: \Name

Using Grouping for functions and defines: This would allow the programmer to sort a group of functions or definitions that belong together to better organize them; ie grouping all the set functions and grouping all the get functions. Use the /*! \name labelA to define a group with a label which would be what appears at the heading of the group in the documentation. In the documentation block of name you can write comments which apply to all of the items that you wish to group. Again note the usage of the tags \{ and \} to demarcate the beginning and end of the grouping. Please note in order for this grouping to work the actual items still need to be individually marked with doxygen documentation.

/*! \name Operators defined by macros.

  These macros are used to create some basic operators with different
  types.  They shouldn't be used unless you are creating a cisMatrix
  with a new data type.  In cisVec3Matrix.h, these operators are
  defined for cisVec3.  To see all the operators created, check the
  macro cisMATRIX_INDENTED_OSTREAM_HEADERS
  cisSUM_MATRIX_OPERATOR_HEADERS, cisACCUM_MATRIX_OPERATOR_HEADERS and
  cisSCALE_MATRIX_OPERATOR_HEADERS definition in file
  cisMatrixMacros.h.
*/

/*! \{ */

/*! Output stream operators. */
cisMATRIX_INDENTED_OSTREAM_HEADERS(cisVec3);

/*! Summation operators. */
cisSUM_MATRIX_OPERATOR_HEADERS(cisVec3, cisVec3, cisVec3);

....
....

/*! \} */

Methods

To comment a method of a class, create your documentation block preceding the method declaration in the .h file.
Inside these documentation blocks, descriptive text of the method is included as well as the parameters, return value and related functions; doxygen uses the \param keyword to allow for descriptions of parameters, the \return keyword to allow for a description of what the method returns. A discussion of how to link keywords without using \sa follows.

 /*! First Method 
   \param a the length
   \param b the height
   \return Area is returned
   \sa Version 
  */
  int method1(int a, int b);

#Defines

Use the \def variable_name command in order to specify that variable_name is a #define value. This documentation block should precede the actual code.

/*! \def cisTracker_INVALID                                                                                  
  The Tracker is invalid                                                                                      
 */
#define cisTracker_INVALID    0

Macros

Use the \def Macro(param1,param2) syntax similar to the #define syntax for macros. To refer to the actual variables use the \parametername to refer to the specific parameter; for the above macro you would use \param1 label1 and \param2 label2 to link the labels to the definitions of the parameter.

/*! \def cisSIND(x)
  sin of an angle \x x in degrees 
 */
#define cisSIND(x) (sin(cisDEG_2_RAD(x)))

Typedefs

Use the \var command to specify that the doumentation block is specific for a type definition. However by default if you place a documentation block immediately preceding a typedef statement; it will be automatically linked to the type definition code.

/*!
  Incremental Status typedef used to keep status of the tracker using the
  constants defined above.
 */
typedef cisInt cisTrackerStatus;

Linking

In the html documentation produced, doxygen allows for the linking of the names of classes, methods and variables to their definitions. Usually the keywords are automatically linked, but there are some special cases where specific syntax is required. To generate links to these members without using the \sa or \see tags, the proper syntax is required

To link a method of a class: ie cisTracker's GetStatus method in the doxygen comments; use cisTracker::GetStatus
Include the parameters in the above example in order to distinguish between overloaded methods;ie cisTracker::GetStatus(int) and cisTracker::(int,int)
To link a protected member of a class:ie cisTracker's ToolFileList use the syntax cisTracker#ToolFileList
To link to a global enumeration or #define, simply add a "#" infront of the #define/enum name. ie: Global_enum; use #Global_enum
To link to a typedef use "::" preceding the name of the typedef ie:for cisTrackerStatus use ::cisTrackerStatus
To link to the constructor of class ie: for class cisTracker use cisTracker::cisTracker
To link to the destructor of class ie: for class cisTracker use cisTracker::~cisTracker

For a documentation block for a class; there is a condensed syntax to be used for the above since it can be assumed that the keywords will be contained inside of the class you are writing comments for. These rules are:

To link to a method such as GetStatus simply use GetStatus()
To link to a member such as ToolFileList use #ToolFileList
To link to the constructor of class ie: for class cisTracker use #cisTracker or cisTracker()
To link to the destructor of class ie: for class cisTracker use ~cisTracker() or #~cisTracker

Anything with a "." that does not end a sentence is considered part of a filename and will automatically be linked.
In some cases we want to link a word in our documentation block to some other keyword: to do this we use the \link tag. The \link tag is followed by the keyword where we want to link to and then by the text to which the link will span; this works similarly to the a href anchor tags in html. The \endlink tag indicates where the end of the link is in accordance to the text.

  /*!
    Initially sets tracker status to \link #cisTracker_INVALID 'invalid'\endlink; Implementation class 
    should call LoadConfiguration(), Initialize(), and InitializeTools()
   */

In this case the text 'invalid' will be linked to the definition of cisTracker_INVALID.

Lists

Doxygen also supports the usage of bulleted lists.

To create a ordered list like the < ol > and < li > html tags use the "-#" ordered list

For an unordered list use the "-" tag which works similarly to the < ul > and < li > tags

Unordered list example:

/*!
   cisTrackerTool Stati:
 
   - #cisTrackerTool_INVALID 
     Tool definition was found to be invalid
   - #cisTrackerTool_NOT_AVAILABLE
     Tool definition is valid, but tool either missing or cannot
      be found by the tracker
   - #cisTrackerTool_AVAILABLE
     Tool is valid, and seen by tracker
   - #cisTrackerTool_INITIALIZED
     Tool is initialized (ready to be tracked)
   - #cisTrackerTool_TRACKING
     Tool is currently being tracked (though not visible)
   - #cisTrackerTool_VISIBLE
     Tool is being tracked and is visible to tracker
 
 */

Ordered list example

/*!
   -# #cisTracker_INVALID: Tracker is invalid
   -# #cisTracker_VALID: Tracker is created but unavailable
   -# #cisTracker_AVAILABLE: Tracker is available but not initialized 
   -# #cisTracker_INITIALIZED: Tracker is initialized, but tools are not initialized
   -# #cisTracker_VALID_TOOLS: Tracker and Tools are initialized but tracker is not tracking
   -# #cisTracker_TRACKING: Tracker & Tools are initialized and the tracker is tracking the \link cisTrackerTool cisTrackerTools\endlink contained in the cisTracker#Tools Vector.
 
 */

Formulas

You can use latex to create png files of formulas by using the \f$ tag to open the formula block inside a documentation block. And use the same tag of \f$ to close the formula block.

/*!
  \f$ R.x * R.y * R.z \f$
 
 */