Block Commands
Doc comments get their structure from block commands: the paragraphs, lists, tables, code listings, and admonitions that make up a description. Each command starts a new block, and the text after it, on the same line or below, is its content.
Paragraphs and headings
Plain prose is already a paragraph. Consecutive lines join into one paragraph, and a blank line starts the next. The first paragraph is the brief; everything after it is the detailed description. When you want to be explicit, @details opens the detail section.
Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/paragraph.cpp[]Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/paragraph.adoc[]
A heading (@par) splits a long description into labelled sections. The text on the @par line is the heading; the lines beneath it are the section body.
Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/heading.cpp[]Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/heading.adoc[]
Lists and tables
A list follows the Markdown convention: lines that begin with - become bullets. @li and @arg are Doxygen-compatible aliases for a single item.
Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/list.cpp[]Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/list.adoc[]
A table uses HTML <table> markup, which gives you full control over headers, rows, and cells.
Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/table.cpp[]Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/table.adoc[]
Code blocks
A code block reproduces source verbatim. Fence it with @code and @endcode, and tag the language (@code{.cpp}) so the highlighter knows what to do. @verbatim and @endverbatim are the same idea without highlighting.
Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/code-block.cpp[]Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/code-block.adoc[]
Admonitions
Admonitions call out something the reader should not miss. The five kinds, @note, @tip, @important, @warning, and @caution, share one shape and differ only in how they are styled. The text after the command is the admonition body.
Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/admonitions.cpp[]Unresolved include directive in modules/ROOT/pages/commands/blocks.adoc - include::example$snippets/commands/admonitions.adoc[]