Documenting ITK

The ITK code documentation is available online at https://itk.org/Doxygen/html/.

By default, the latest released documentation version is displayed, but documentation for previous versions is available at by choosing the appropriate version at the bottom of the above page, e.g. https://itk.org/Doxygen53/html/index.html.

Using Doxygen for C++ code

Dependencies

Generating a complete Doxygen documentation requires (besides CMake and the ITK source code):

Preferable:

  • Dot from GraphViz for generating inheritance and dependency graphs.

Generating the Doxygen documentation

Generating the Doxygen documentation for ITK requires:

  • The BUILD_DOCUMENTATION CMake flag be turned ON.

  • Build the project as you would normally do: it will build both the ITK libraries/binaries and the Doxygen documentation.

Doxygen will then generate the documentation for enabled modules. So if you want to generate the complete doxygen documentation you would need to turn ON the ITK_BUILD_ALL_MODULES CMake flag.

How to document ITK

Users are referred to Doxygen’s documentation manual, and the command reference list for detailed instructions.

Below is a simple example of how to document ITK code.

Classes

A minimal example to document an ITK class is the following:

/**
 * \class MyAwesomeClass
 * \brief Short Description of MyAwesomeClass.
 *
 * Here you can start writing a more detailed documentation for MyAwesomeClass.
 *
 * To document each template parameters use:
 * \tparam T1 documentation for the first type
 * \tparam T2 documentation for the second type
 * \tparam VDimension documentation about the third template parameter which seems to be related to the Dimension
 *
 * You can make implicit references to any other ITK class, by just writing their names, e.g. Image, ImageRegion...
 *
 * You can also set the group(s) the class belongs to:
 * \ingroup MySpecialGroupOrModule1
 * \ingroup MySpecialGroupOrModule2
 *
 * Or you can create make a dedicated section "see also":
 * \sa Image
 * \sa ImageRegion
 */

template< class T1, typename T2, unsigned int VDimension >
class MyAwesomeClass
{
public:
  /** You can directly write the documentation for PixelType */
  typedef PixelType T1;
};

The most common Doxygen commands used to document classes in ITK are:

Methods and functions

Similar to classes, methods and functions can be documented using Doxygen commands.

A minimal example for a method documentation is the following:

/** \brief A short description of Method1.
 *
 * A more detailed documentation for Method1.
 *
 * \param[in] iP1 Documentation for the first parameter, an input parameter.
 * \param[in] iValue Documentation for the second parameter, an input parameter.
 * \param[out] oValue Documentation for the third parameter, an output parameter.
 * \param[in,out] ioP2 Documentation for the fourth parameter, an input/output parameter.
 * \return Description about the return value.
 */
int Method1(PixelType iP1, unsigned int iValue, unsigned int& oValue, PixelType& ioP2) const

The most common Doxygen commands used to document methods and functions in ITK are: