Documentation of Variables and Modules in C++

28.4. Documentation of Variables and Modules in C++#

The description for all variables, modules an module parameters must be valid reStructuredText. Parameters for variables should be documented using Google Style Docstrings.

It is advisable to use raw string literals in C++ to be able to easily write multi line strings. A raw string literal starts with R"delimiter( and ends with )delimiter". It can span multiple lines similar to the python multi line strings (""" or '''). The delimiter can be chosen freely and can also be empty. usually for documentation strings we recommend something like

R"DOC(This will be the actual string
and it can span multiple lines)DOC"

As an example, the following code to register a variable

REGISTER_VARIABLE("example_variable_documentation(param1, param2, ...)",
                  functionNameHere, R"DOC(
Example variable documentation showing the use of markup.
All the reStructuredText commands as in python function docstrings are valid
here and since it is a raw string we can wrap the string however we see fit:

* we can also add bullet lists
  with multi line entries and *inline* **markup**
* we can add links to other variables and formulas: :math:`x^2`
* and provide documentation for the parameters

Warning:
  Also warnings or info messages

See Also:
  :b2:var:`example_variable_documentation` (linking to ourselves :D)

Parameters:
  param1 (int): parameter description
  param2 (str): and even more parameter descriptions
    across various lines
    and even in **bold**

    Empty lines start a new paragraph in here

)DOC");

would show up in the documentation as

example_variable_documentation(param1, param2, ...)#

Example variable documentation showing the use of markup. All the reStructuredText commands as in python function docstrings are valid here and since it is a raw string we can wrap the string however we see fit:

we can also add bullet lists with multi line entries and inline markup
we can add links to other variables and formulas: \(x^2\)
and provide documentation for the parameters

Warning

Also warnings or info messages