Documentation Guide

Using Sphinx and Exhale

Installation

Documentations are build using Sphinx with the Read The Docs theme.
We are using Exhale to embed the Doxygen generated C++ documentation into Sphinx.
As well as having Doxygen installed you also need to install the following python packages:
- sphinx
- exhale
- sphinx-rtd-theme
- myst_parser
You can also use the provided requirements.txt file in the docs directory. But the requirements here are frozen to ensure that they work correctly on Read The Docs’ build servers.

pip install -r requirements.txt

Usage

Documentation can be build using the following commands

cd docs
make html

This will generate the necessary html files in _build/html and you can view the documentation by opening the index.html file located there.

Documenting Code

Doxygen will automatically generate docs from specially marked comments in the code
For this project, we prefer the QT style marked comments shown below

/*!
 * ... text ...
 */

//!
//!... text ...
//!

In general we will try to use the QT commenting styles as much as possible.

Documenting Classes/Structs

The line comment is a brief description of the class.
The block comment is a more detailed description of the class.
Remember that doxygen will automatically add class hierarchy and methods to the documentation so no need to mention them here.

//!  A test class. 
/*!
  A more elaborate class description.
*/
class TestClass {};

Documenting Data Members

Data members inside classes are commented using a brief description and a detailed description.
Same pattern as classes

class TestClass {
  protected:
    //!  A brief description.
    /*!
      More detailed description.
    */
    int p;
};

Documenting Enums

Each value and the whole enum must be given a short description as show below.

//! Enum Description
enum TEnum { 
 TVal1, /*! Brief Description of TVal1 */
 TVal2, /*! Brief Description TVal2 */
 TVal3  /*! Brief Description TVal3 */
};

In very critical cases the enum itself can be given a more detailed description using the same syntax as a class (see previous section).

Documenting Functions and Methods

The line comment is a brief description of the function. For example, these will be used when viewing all the methods of a class. This should not exceed a single line (~80 chars max).
First part of the block comment is a more detailed description of the function and can be as long as you wish.
“@param” is used to describe parameters a function takes. It should be followed by the name of the parameter and a short description of it.
“@tparam” is used to describe templated parameters of a function. It should be followed by the name of the templated parameter and a short description of it.
“@return” is used to describe the return value of the function.

//! Brief Description.
/*!
  Detailed Description.
  @param a an integer argument.
  @param s a constant character pointer.
  @tparam T a templated argument
  @return The test results
*/
template<typename T>
int testMe(int a, const char *s){}