standardese looks for documentation comments as shown in the following example:
/// A regular C++ style documentation comment.
/// Multiple C++ style comments are merged automatically.
/// This line has *two* leading whitespaces because one is always skipped.
//! A C++ style comment using an exclamation mark.
/// It will also merge with other C++ style comments.
//! But don't worry, also with the exclamation mark styles.
/** A C style documentation commment. */
/** This is a different comment, they aren't merged.
* But you can be fancy with the star at the beginning of the line.
* It will ignore all whitespace, the star and the first following whitespace.
*/
/*! You can also use an exclamation mark. */
/// But neither will merge with any other comment.
int x; //< An end-of-line comment.
/// It will merge with C++ style comments.
int y; //< But this is a different end-of-line comment.
A comment corresponds to the entity on the line directly below or on the same line.
You can document all entities that way except files (use file command), namespaces (use entity command),
and inline entities such as parameters or base classes (use param/tparam/base command or entity command).
Inside the comment you can use arbitrary* Markdown* in the documentation comments and it will be rendered appropriately.
The Markdown flavor used is CommonMark. standardese does not support inline HTML (for obvious reasons) or images. Inline HTML that isn’t a raw HTML block will be treated as literal text. This allows writing
vector<T>without markup or escaping in the comment, for example.
Note: CommonMark allows hard line breaks with a backslash at the end of the line. But the C preprocessor uses a backslash to combine multiple lines into one. For that reason you cannot use a backslash there, instead you can use a forward slash.