A command is used to control the documentation generation in some way. A text that begins with a command doesn’t appear in the output documentation at all.
There are the following commands:
verbatim - This command isn’t like the other commands.
It can happen anywhere in a line — i.e. where CommonMark allows an inline entity like emphasis.
The text following the command until an end command or the end of the line will be inserted as-is into the output.
end - This command ends the currently active section, see below.
This can be used to extend a section to multiple paragraphs.
exclude {arg} - Manually excludes an entity or part of it from the documentation.
If you don’t specify an argument, it won’t appear at all, not even in the synopsis.
It is as if the entity never existed in the first place.
If you specify return as argument, the return type of the function will be hidden in the synopsis.
If you specify target as argument, the target of the namespace/type alias or underlying type of the enum will be hidden in the synopsis.
unique_name {name} - Overrides the unique name of an entity (e.g. for linking):
/// Some documentation.
/// I can now link to `bar()` by writing [foo]().
///
/// \unique_name foo
void bar(int a, int c);
Note that if you override the unique name of a parent entity, this will also affect the unique names of child entities. If the unique name starts with ‘*’ or ‘?’, it will be a relative unique name, i.e. the unique name of the parent entity will be prepended to it (with seperator ‘::’ if needed).
output_name {name} - Overrides the output name of a file.
This will only change the base name, the doc_ prefix and extension are still handled separately.
Useful if there are multiple files with the same base name in a project, e.g a .hpp and .h header.
synopsis {string} - Overrides the synopsis in the output.
You can pass any string that will be rendered instead of the actual synopsis.
Use \n to render a newline and use \t to render a tab.
synopsis_return {string} - Like synopsis, but only overrides the return type of the function.
group <name> [heading] - Add the entity to a member group.
A member group consists of multiple entities that are direct members of the same entity (i.e. class, file, namespace,…) which will be grouped together in the output.
For example:
/// \group foo A heading
/// This is in the group `foo`.
/// Because this is the first entity in the group, it will be the "master".
/// the group comment will be this comment, the group unique name will be this unique name, ...
/// The optional heading (everything after the first whitespace) will be shown as heading in the output.
void func();
/// \group foo
/// This entity will be added to the same group.
/// As it is not the first occurence of the group,
/// this comment here will be ignored.
/// But you can still use commands to modify this entity.
void func(int);
/// This entity is not part of the group.
void func(char);
/// \group foo
/// But this one is (again, comment ignored).
void func(short);
This will write the synopsis of all group members together and use the documentation text of the first entity. The group name only needs to be unique for one given scope. Note: It will only show inline documentation for children, so don’t use it on containers.
module {name} - Add the entity to a module.
A module is just a way to group entities together,
it will be inherited by all children.
There is no need to define a module, but if you do,
simply use the command in first place of a module and you can add documentation for it:
/// This is an entity in the module 'bar'.
/// \module bar
void foo();
/// \module bar
/// This is the documentation for the module 'bar',
/// because the command was the first one.
output_section {name} - Generates a little section comment in the synopsis above the entity.
This is implictly used for member groups with the group name as output section name,
if the option output.show_group_output_section is true (the default).
If a member group name starts with ‘-’, it will never be used (the minus won’t be shown).
Given the following input:
/// Some int getter.
/// \output_section Getter functions
int get_i();
/// Some float getter.
float get_f();
/// Some int setter.
/// \output_section Setter functions
void set_i(int val);
/// Some float setter.
void set_f(float f);
It will generate a synopsis like this:
//=== Getter functions ===//
int get_i();
float get_f();
//=== Setter functions ===//
void set_i(int val);
void set_f(float f);
entity {unique-name} - If put in the first place of a comment, names the entity to document,
this allows “remote” comments:
void foo();
/// \entity foo
/// This comment has no corresponding entity.
/// But the command specifies the entity it will belong to.
It also mixes with unique_name as you might expect.
file - A shorthand for \entity current-file-name.