Doxygen

Doxygen is an open-source, powerful system for automatically generating documentation from source code. To use Doxygen effectively, the developer must insert comments, delimited in a special way, that Doxygen extracts to produce the documentation. While there are a large number of options to Doxygen, developers at a minimum should insert the following Doxygen commands.

Where to find it?

How to generate?

  1. Install
  2. When using CMake, turn ON BUILD_DOCUMENTATION
  3. Compile the doc target:
    $ make doc
  4. It creates a new folder Documentation/html in the ${GOFIGURE2_BINARY_DIR}. Finally you only need to open index.html with your favorite web browser.

Note that to generate a doxygen documentation with links to external documentations (VTK, ITK, Qt), you need to turn the LINK_EXTERNAL_DOC flag ON. It must be understood that generating such a documentation is much longer process than the usual one!

Documenting a Class

Classes should be documented using the \class and \brief Doxygen commands, followed by the detailed class description:

 /** \class Object
* \brief Base class for most itk classes.
*
* Object is the second-highest level base class for most itk objects.
* It extends the base object functionality of LightObject by
* implementing debug flags/methods and modification time tracking.
*/

class Object

\example

\image

Documenting a Method

Methods should be documented using the following comment block style as shown in the following example.

 /**
* \brief Access a pixel. This version can be an lvalue.
* \param[in] index
* \return pixel value at index
*/

TPixel & operator[]( const IndexType & index )
{
return this->GetPixel( index );
}

The key here is that the comment starts with /**, each subsequent line has an aligned *, and the comment block terminates with a */.

\todo keyword

This keyword must be used as much as possible to let everyone knows what has to be fixed, and pertinent comments in the code. This will automatically generate a todo page with all todo messages written in the code.