We use Doxygen to generate documentation.

To compile the documentation and open it in your default browser, you just need to run (after installing doxygen):

$ ./dev.py doc

Writing documentation

General format:

[!NOTE]

• Use \ to include Doxygen commands like \brief.
• Always put a \brief.
• Do not hesitate to use \ref (syntax: \ref path "name visible in doxygen" like \ref holovibes::SettingsContainer::get "get").
• When using template (function/class) add a \tparam and explain what type is expected and what it's used for.

For multi-line comments use:

/*! 
 * \brief {description}
 */

For single line comments:

/*! \brief {description}  */

If more than 3 functions/variables shares a common logic you can create a group like so:

/*! \name {category name}
 * \{
 *
 * {category description}
 */

/*! {description} */
int attribute = 1;
/*! {description} */
void someMethod();

// ...

/*! \} */

Files

You must comment each header files and should comment each source file with the following comment at the beginning of the file (on the first line, before any directive):

/*! \file {file_name}
 *  \brief {description}
 */
#pragma once
// ...

Describe:

• what is defined
• how it works
• the goal
• where it can be used
• how to use the implemented features with small code snippet.

[!TIP] You can take a look at settings_container.hh

Enum

Add these lines before an enum declaration:

/*! \enum {name}
 *  \brief {description}
 */

[!NOTE]

• Describe the goal/meaning of the enum and where it can be used.
• You are encouraged to comment enum member. If you do so, comments all enum members.

Class, struct

Add this before the declaration:

/*! \class {name}
 *  \brief {description}
 */

Follow the same practices as with files.

Functions/methods

A complete function comments looks like:

/*!
 * \brief {small description of is expected in input, what is outputted and briefly what it does}
 *
 * {advanced description with \ref and code snippet}
 *
 * \param[in]     {var_name} {description}
 * \param[out]    {var_name} {description}
 * \param[in out] {var_name} {description}
 * \tparam        {template_name} {description}
 *
 * \throw         {exception_name} {description on when}
 *
 * \return        {description}
 */

Modifiers	Description
in	Used when the arguments is only read inside the function (ex: scalar values)
out	Used when the function stores something in the variable (ex: pointers)
in out	Used when the function reads and also writes to the variable (ex: inplace function)

[!WARNING]

• No need to comment getters and setters or any other function that does not have any logic.
• Prefer commenting functions in the header.

Variables/attributes

Prefer using single line comment