A section is the basic way of standardese documentation.
It supports all the sections the C++ standard uses, as explained in the example.
Those sections will create a paragraph in the output prefixed with a human readable name.
There are two special sections, brief and details.
They are not labeled in the output.
Unlike for a command text following a section is included in the output.
A section is active for the rest of the paragraph, a hard line break or until another special command is encountered.
Any brief sections will be merged together automatically.
If you don’t specify a section for a paragraph, the first paragraph will be implictly brief, all others implictly details.
/// \brief This text is brief.
///
/// This is implictly details.
/// \effects This is effects.
/// This is still effects.
/// \returns This is returns./
/// Due to the hard break this is details again.
///
/// \notes This is notes.
/// \notes This is a different notes.
If you have a section with the form \<section> <arg> - <text>, it will generate a key value list in the output.
Then you can also add other key-value pairs in each line.
Use _ as argument for an empty key.
Surround the argument in [<arg>] and it will create a link where <arg> is also the destination,
i.e. like a regular entity link of the form [<arg>]().
Note: Due to implementation reason you can’t use a real CommonMark link as key.
The value consists of CommonMark inline formatting until the reset of the section or a new key is encountered. For example:
/// This is documentation text (implictly brief btw).
/// \returns 0 - Everything okay (first key-value pair).
/// 1 - There was an input error (second key-value pair).
/// This is *still* the second key-value pair.
///
/// This is normal text as the paragraph ended.
This will generate a list of possible return values in the output.
This is also how the see section is intended:
/// Some documentation...
/// \see [this_type] - Put a description here (optional)
/// [this_func()] -
/// [std::vector<T>] -
It will generate a “See also:” list in the output with links to the entities.