Document the code

OpenTwin uses Doxygen to generate the Code. There are many ways to document the code by following the Doxygen style guide. Here we have listed a guide that OpenTwin agreed on to use for all of the files in the OpenTwin projects.

The ‘//!’ prefix should be used to indicate a Doxygen comment. The advantage the ‘//!’ prefix is that a code block containing multiple methods or blocks of Doxygen comments can be easily commented out by using /* ... */.

To address a Doxygen keyword use the \ prefix.

Detailed descriptions can be added without a keyword in the lines after the \brief.

Classes

Every class should have a \brief set. The class keyword is used to create references in the documentation. The brief should contain a short text description of the class which is a single line.

//! \class MyClass
//! \brief The MyClass is used to store two integers.
//! Here a more detailed description could be added
//! which may span over multiple lines and also contain
//! #Markdown
//! syntax.
class MyClass {
    ...
};

Functions

Function comments should be added to the header file. Some IDEs support the Doxygen format and will display it in the ToolTips.

Every function should have a \brief set aswell as a \param for every parameter unless the function/parameter name is self-explanatory (e.g. setter and getter methods). If the return is not described in the \brief or detailed description add a \return.

//! \fn bool switchToRed(bool _delay)
//! \brief Brief description.
//! More detailed description.
//! More detailed description.
//! \param _delay Parameter description.
//! More _delay parameter description.
//! \return Return value description.
//! More return value description.
bool switchToRed(bool _delay);

Class Members

Class members should have a \brief set. Adding \var allows to reference that value.

class A {
    int m_int; //! \brief Brief description.

    //! \var m_dbl
    //! \brief Description.
    //! More detailed description.
    //! More detailed description.
    double m_dbl;
};

Enums

Enums should have a \brief set for the enum and every entry in the enum.

//! \enum MyEnum
//! \brief Brief description.
//! More detailed description.
//! More detailed description.
enum MyEnum {
    MyValue, //! \brief Description

    //! \brief Brief description
    //! More detailed description.
    //! More detailed description.
    //! \warning Warning box content.
    //! More warning box content.
    MySecondValue
};

Macros

Macros or preprocessor definitions should have a \brief set.

//! \def MY_MACRO
//! \brief Brief description.
//! More detailed description.
//! More detailed description.
#define MY_MACRO

Namespaces

Notes Questions and Warnings

To display a box around the text use either \note, \question or \warning.

//! \brief Brief description.
//! More detailed description.
//! More detailed description.
//! \warning Warning box content.
//! More warning content.
//! \note Note box content.
//! More note content.
//! \param _force Parameter description.
//! \return Return value decription.
bool shutdown(bool _force);

Doxygen Keywords

Here is a little cheat sheet for the common doxygen keywords.

Common Doxygen Commands and Keywords
Command/Keyword	Description	Example
a	Documents a parameter or return value as an argument.	//! Foo uses (\a _arg) to determine what to do. void foo(int _arg);
addtogroup	Creates a new group or adds entities to a group.	//! \addtogroup TestGroup @{ bool foo(void); bool boo(void); //! @}
attention	Documents a note or additional information that requires special attention.	//! \attention Attention text
brief	Provides a brief description of an entity.	//! \brief Brief description. void foo(void);
bug	Documents a known bug.	//! \bug This is doing nothing
c	Marks text as code.	//! Foo uses an (\c int) as a argument. void foo(int _arg);
class	Documents a class.	//! \class MyClass class MyClass {};
code	Indicates the start of a code block.	//! \code //! Code line //! Code line //! \endcode
copybrief	Copies the brief description from another entity.	//! \brief Brief description that will also be copied to B. class A {}; //! \brief Brief description for B. //! \copybrief A class B : public A {};
copydetails	Copies the detailed description from another entity.	//! \brief Brief description //! Detailed description that will be copied to B. class A {}; //! \brief Brief description for B. //! \copydetails A class B : public A {};
def	Documents a macro or preprocessor definition.	//! \def MY_MACRO #define MY_MACRO
defgroup	Defines a group.	//! \defgroup MyGroup Brief group description.
deprecated	Marks an entity as deprecated.	//! \deprecated Use boo instead. [[deprecated("Use boo instead")]] void foo(void) { ...
enum	Documents an enumeration.	//! \enum MyEnum enum MyEnum {};
enumclass	Documents a scoped enumeration.	//! \enumclass MyEnumClass enum class MyEnumClass {};
file	Documents a file.	//! \file MyFile.h
fn	Documents a function.	//! \fn void foo(void) void foo(void);
ingroup	Assigns an entity to a group.	//! \ingroup TestGroup
label	Creates a unique identifier to the specified entity allowing to reference it later.	//! \label label_name void foo(void);
link	Creates a hyperlink to another entity.	//! For more information check \link void boo(void) \endlink void foo(void);
mainpage	Documents the main page of the project.	//! \mainpage The Main Page Title
namespace	Documents a namespace.	//! \namespace MyNamespace namespace MyNamespace {}
namespacealias	Documents a namespace alias.	//! \namespacealias MyAlias namespace MyAlias = test;
note	Documents a note or additional information.	//! \note Note text
param	Documents a function parameter.	//! \param _myParam Brief parameter description. void foo(int _myParam);
page	Documents a page (e.g., overview, tutorial).	//! \page MyPageName Page Title //! Brief page description
pagebreak	Inserts a page break in the documentation.	//! \pagebreak
ref	Creates a cross-reference to another entity.	//! For more information check out \ref label_name.
relates	Indicates a related function or class. Is used to establish relationship between different entities if not done automatically.	class MyClass {}; //! \relates MyClass void foo(MyClass _arg);
return	Documents the return value of a function.	//! \return Brief return description. bool foo(void);
see	Provides a cross-reference to another entity.	void MyClass::foo(void); //! \see MyClass, foo void boo(void);
since	Documents the version when an entity was introduced.	//! \since YYYY-MM-DD
struct	Documents a struct.	//! \struct MyStruct struct MyStruct {};
tparam	Documents a template parameter.	//! \tparam T Brief template parameter description. template <class T> void foo(T _arg) {}
todo	Marks a to-do item in the documentation.	void foo(void) { //! \todo Think of functionality }
typedef	Documents a type definition.	//! \typedef MyType typedef int MyType;
union	Documents a union.	//! \union MyUnion union MyUnion {};
unionclass	Documents a scoped union.	//! \unionclass MyUnionClass union class MyUnionClass {};
until	Documents the version until which an entity exists.	//! \until YYYY-MM-DD
var	Documents a variable or member variable.	class A { //! \var m_var int m_var; };
warning	Documents a warning.	//! \warning Warning text

Markdown Syntax

Here is a little cheat sheet for markdow comments. Note that the spaces after the prefixes are mandatory. Also note that markdown uses spaces for the indent (which should be used anyway).

# Level 1 Header
## Level 2 Header
    ```
###### Level 6 Header


Regular text.
More regular text.

    Code block.
    More code.

- - -     // This is a horizontal ruler

> Multiline
> block quote

*text emphasis*
**strong text emphasis**

~~striketrough text~~

- Bulletlist Item

    Detailed Text

- Bulletlist Item 2
    + Child item 1
    + Child item 2
- Bulletlist Item 3
    1. Numbered child 1 list 1
    1. Numbered child 2 list 1
    2. Numbered child 1 list 2
    3. Numbered child 1 list 3