We use Doxygen to generate documentation.

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

$ ./dev.py doc

Writing documentation

General format:

[!NOTE]

• Start comments with /*! and close with */.
• 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 can 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]

• Prefer commenting functions in the header except for functions exposed only inside a translation unit.

Variables/attributes

Prefer using single line comment

Github wiki

Please update the wiki to reflect your changes and don't hesitate to create new pages if you think something is missing.

Pay more attention to:

• In the setup page always put the latest version of software you use.
• Update Code structure and UI code structure if: you wake significant changes to a documented system, add a new one or if you think something is missing.

[!WARNING]

• Be concise and direct, the wiki is made to be read quickly and get a general yet detailed understanding.
• There is never too much documentation.