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.
/** Computes the absolute value of an integer.
Returns the input unchanged when non-negative,
otherwise returns its negation.
*/
int absolute(int x);absolute
Computes the absolute value of an integer.
Synopsis
Declared in <paragraph.cpp>
int
absolute(int x);Description
Returns the input unchanged when non‐negative, otherwise returns its negation.
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.
/** A configuration record.
@par Thread safety
Instances are immutable after construction
and may be shared across threads without locking.
*/
struct config { };config
A configuration record.
Synopsis
Declared in <heading.cpp>
struct config;Thread safety
Instances are immutable after construction and may be shared across threads without locking.
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.
/** Initializes the connection.
The function performs three steps in order:
- Allocates the socket.
- Performs the handshake.
- Caches the credentials.
*/
void connect();connect
Initializes the connection.
Synopsis
Declared in <list.cpp>
void
connect();Description
The function performs three steps in order:
-
Allocates the socket.
-
Performs the handshake.
-
Caches the credentials.
A table uses HTML <table> markup, which gives you full control over headers, rows, and cells.
/** Returns a status code describing the result of `parse`.
<table>
<tr><th>Code</th><th>Meaning</th></tr>
<tr><td>0</td><td>Success</td></tr>
<tr><td>1</td><td>Syntax error</td></tr>
<tr><td>2</td><td>I/O error</td></tr>
</table>
*/
int parse_status();parse_status
Returns a status code describing the result of parse.
Synopsis
Declared in <table.cpp>
int
parse_status();Description
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Syntax error |
2 |
I/O error |
Return Value
a status code describing the result of parse.
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.
/** Computes a hash code for a byte sequence.
Typical use:
@code
auto h = compute_hash("hello", 5);
@endcode
*/
unsigned compute_hash(const char* data, unsigned n);compute_hash
Computes a hash code for a byte sequence.
Synopsis
Declared in <code‐block.cpp>
unsigned int
compute_hash(
char const* data,
unsigned int n);Description
Typical use:
auto h = compute_hash("hello", 5);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.
/** Closes the handle.
@note Closing a handle invalidates any iterators
that point into the underlying buffer.
@warning Do not call this from a destructor that
runs during program termination.
@tip Prefer the RAII wrapper `scoped_handle`,
which closes automatically at scope exit.
*/
void close_handle();close_handle
Closes the handle.
Synopsis
Declared in <admonitions.cpp>
void
close_handle();Description
|
Closing a handle invalidates any iterators that point into the underlying buffer. |
|
Do not call this from a destructor that runs during program termination. |
|
Prefer the RAII wrapper |