Metadata Commands
A metadata command attaches a structured fact to the symbol instead of adding prose to the description. MrDocs renders those facts in dedicated places: the parameter table, the return-value section, the list of exceptions, and so on.
Summary
The first sentence of a doc comment is the symbol’s summary by default. Reach for @brief (or @short) only when the opening sentence is not the summary you want.
Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/summary.cpp[]Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/summary.adoc[]
Parameters and return value
@param documents one function parameter; MrDocs matches the name against the signature, and an optional [in], [out], or [in,out] records how data flows. @tparam does the same for template parameters, and @returns describes what the function hands back.
Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/resample.cpp[]Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/resample.adoc[]
Errors and contracts
@throws names an exception the function may raise and the condition that triggers it; repeat it for each one. @pre and @post state what must hold before the call and what is guaranteed after it.
Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/transfer.cpp[]Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/transfer.adoc[]
Relationships
@relates ties a free function to a class, listing it among that class’s non-member functions.
Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/relates.cpp[]Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/relates.adoc[]
@see adds an entry to the "See also" section. Its argument is an ordinary paragraph, so put an @ref inside it to link a symbol.
Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/see-also.cpp[]Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/see-also.adoc[]
Symbol flags
Three commands set a flag on the symbol rather than producing visible text. @functionobject marks a constexpr variable as an Algorithm Function Object (AFO): put it on the variable, document the type’s operator() (that is where the AFO’s signature and text come from), and reach for it only when the type has extra members that defeat auto-detection. @seebelow renders a declaration’s body as /* see below */. @implementationdefined hides a type whose definition is not part of the public interface, so its uses render as /* implementation-defined */.
Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/regex.cpp[]Unresolved include directive in modules/ROOT/pages/commands/metadata.adoc - include::example$snippets/commands/regex.adoc[]