Commands Reference

Syntaxes:

A paragraph is the most basic block structure in a doc comment. Any plain text that is not part of another command is treated as a paragraph. Consecutive lines of text are merged into a single paragraph; a blank line starts a new one.

The @details command is an explicit way to begin the detailed description section, but in practice you rarely need it — any text after the brief summary is already treated as detail paragraphs.

See also: Heading

Syntax: @par [title] { content }

The @par command creates a named heading (subsection) inside a doc comment. The text on the same line as @par becomes the heading title; subsequent lines form the body of that section.

See also: Paragraph

Syntaxes:

Creates an unordered (bulleted) list inside a doc comment. You can use the Javadoc/Doxygen @li command, its alias @arg, or Markdown-style dash bullets (`- `). All three syntaxes produce the same list structure.

Syntax: <table>

Creates a table inside a doc comment using HTML table markup. MrDocs parses standard HTML <table>, <tr>, <th>, and <td> elements and converts them to a table in the output format.

Syntaxes:

Inserts a block of preformatted code into the documentation. Everything between the opening and closing tags is preserved verbatim, including whitespace and indentation.

@code and @verbatim produce the same output. Use @code for source code and @verbatim for other preformatted text, though MrDocs treats them identically.

Syntaxes:

Admonition commands wrap a paragraph in a callout block. The five kinds differ in urgency:

The text following the command becomes the body of the admonition block.

Syntax: > text

The AST defines a Quote node, but no parser path produces it yet. When that lands, it will hold a blockquote inside a doc comment.

See also: Paragraph

Syntaxes:

The AST defines a ThematicBreak node, but no parser path produces it yet. When that lands, it will render as a horizontal rule between doc-comment sections.

See also: Heading

Syntax: term : definition

The AST defines a DefinitionList node, but no parser path produces it yet. When that lands, it will hold a definition list of term-description pairs.

See also: List

Syntax: [^label]: text

The AST defines a FootnoteDefinition node, but no parser path produces it yet. When that lands, it will hold the body of a footnote that inline content can reference.

See also: Footnote Reference

Syntax: expression

The AST defines a block-level Math node, but no parser path produces it yet. This is the block form, separate from the inline $…​$ and ... math that already works. When that lands, it will hold a standalone math expression as its own block.

See also: Math

Syntaxes:

The @brief command marks its content as the brief description (summary) of the documented symbol. The first sentence of a doc comment is automatically treated as the brief, so you only need @brief when you want to override that behavior or when the automatic detection does not capture what you intend.

@short is an alias for @brief.

See also: Paragraph

Syntax: @param[<dir>] <name> { description }

The @param command documents a function parameter. Write one @param per parameter you want to describe. The parameter name follows the command, and everything after it is the description.

An optional direction indicator can appear in square brackets between @param and the parameter name to specify how data flows through the parameter.

See also: Template Parameters, Returns

Syntax: @tparam <name> { description }

The @tparam command documents a template parameter. It works like @param, but for type, non-type, and template-of-template parameters.

See also: Parameters

Syntaxes:

The @return command documents the return value of a function. All three spellings are equivalent. You can use multiple @return commands when a function returns a composite value and you want to describe each part separately.

See also: Parameters, Exceptions

Syntaxes:

The @throw command documents an exception that a function may throw. All three spellings are equivalent. The exception type follows the command, and the rest of the line (and continuation lines) describe when or why the exception is thrown.

See also: Returns, Preconditions

Syntax: @pre { description }

The @pre command documents a precondition that must hold before calling the function. You can use multiple @pre commands to list several preconditions; each one renders as a separate bullet in a "Preconditions" section.

See also: Postconditions, Exceptions

Syntax: @post { description }

The @post command documents a postcondition that is guaranteed after the function returns successfully. Like @pre, you can use multiple @post commands to list several postconditions; each renders as a separate bullet in a "Postconditions" section.

See also: Preconditions

Syntaxes:

The @see command adds an entry to the "See also" section of the documented symbol. The argument is parsed as inline content, so you can include cross-references, links, or plain text. Multiple @see commands produce multiple entries.

@sa is a Doxygen-compatible alias for @see.

See also: Cross-reference

Syntaxes:

Declares that the documented free function is logically related to (or a member of) the specified class or struct. MrDocs stores each target in the symbol’s relates field and renders it under Non-Member Functions. @related, @relatedalso, and @relatesalso are aliases for @relates; @memberof behaves the same way.

Syntaxes:

Marks a constexpr variable as an Algorithm Function Object (AFO) (the niebloid pattern: a callable object that stands in for a function). Place the command on the variable or on its function-object record; it never goes on operator(). MrDocs then documents the variable as a function whose signature and text come from the record’s operator() overloads, falling back to the variable’s own doc comment when operator() is undocumented. The record’s own doc comment is not used. With auto-function-objects enabled (the default) a variable whose type has only operator() overloads is detected automatically, so the command is needed only when the type has extra public members that defeat detection. @functor is an alias for @functionobject.

Syntax: @seebelow

Marks the symbol so its synopsis renders as /* see below */ instead of the full declaration, for interfaces whose exact form is unspecified.

Syntax: @implementationdefined

Marks the symbol as implementation-defined, so its details are hidden from the generated documentation.

Syntaxes:

Renders its content in italic (emphasized) style. Use * or _ around the emphasized text. The Doxygen commands @a, @e, and @em emphasize the single word that follows them.

See also: Strong

Syntaxes:

Renders its content in bold (strong) style. Use ** or __ around the bold text. The Doxygen commands @b and @strong bold the single word that follows them.

See also: Emphasis

Syntaxes:

Renders its content in a monospace code font, inline within the surrounding text. Markdown-style backtick delimiters wrap the text to be rendered as code. The Doxygen commands @c and @p apply code formatting to the single word that follows them. The HTML <code> tag is also recognized.

See also: Code Block

Syntaxes:

Renders its content with a horizontal line through the middle, for deleted or deprecated text. Wrap the text in double tildes (~~).

Syntaxes:

Renders its content with a highlighted background, drawing attention to specific words or phrases. Markdown-style double equals signs (==) wrap the text. The HTML <mark> tag is also recognized.

Syntaxes:

Renders its content as superscript, positioned above the baseline. Use for footnote markers, exponents, and ordinal indicators. Wrap the text in carets (^).

See also: Subscript

Syntaxes:

Renders its content as subscript, positioned below the baseline. Use for chemical formulas, mathematical indices, and similar notation. Wrap the text in single tildes (~).

See also: Superscript

Syntaxes:

Renders a mathematical expression. Single dollar signs ($…​$) produce an inline math span that flows within surrounding text. Double dollar signs (...) produce a display math block, typically centered on its own line. The content between the delimiters is treated as a literal math expression and is not parsed for Markdown or other formatting.

See also: Code Span

Syntaxes:

Creates a hyperlink to an external URL. The Markdown form puts the visible text in square brackets and the URL in parentheses. The HTML form uses an <a> tag with an href attribute.

See also: Cross-reference, Image

Syntaxes:

Embeds an image inline. The Markdown form is an exclamation mark, alt text in square brackets, then the source path in parentheses. The HTML form uses an <img> tag with src and alt attributes.

See also: Link

Syntaxes:

Creates a cross-reference to another documented symbol. The @ref command takes a symbol name (optionally namespace-qualified) and produces a link to that symbol’s documentation page. Qualified names use :: separators (e.g., @ref A::f1, @ref ::A::f1). Operator names are supported (e.g., @ref F::operator+).

See also: Link, See-also

Syntax: [^label]

The AST defines a FootnoteReference node, but no parser path produces it yet. When that lands, it will hold an inline reference to a footnote definition.

See also: Footnote Definition

Syntaxes:

Copy documentation from another symbol. @copydoc copies the whole doc comment (brief, description, and every metadata block); @copybrief copies only the brief; @copydetails copies only the detailed description. Useful for overloads, redeclarations, and wrappers that share documentation with another symbol.

See also: Copy Brief, Copy Details

Syntaxes:

The <br> HTML tag marks a hard line break inside inline content. MrDocs accepts both <br> and the self-closing <br/>. The visible rendering is still being refined: the parser consumes the tag without emitting an explicit line-break element yet.

See also: Soft Break

Syntaxes:

The AST defines a SoftBreak node, but no parser path produces it yet. A soft break is a line break that renderers may collapse to a space, in contrast to the hard <br> break.

See also: Line Break