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.

Summary
/** @brief Connects to a remote endpoint.

    Establishes a TCP connection to the given host and port
    and returns a handle for subsequent operations.
 */
int connect_to(const char* host, int port);
Preview
connect_to

Connects to a remote endpoint.

Synopsis

Declared in <summary.cpp>

int
connect_to(
    char const* host,
    int port);
Description

Establishes a TCP connection to the given host and port and returns a handle for subsequent operations.

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.

Parameters, template parameters, and return value together
/** Resamples an audio signal to a new sample rate.

    @tparam Sample The sample type, usually `float` or `short`.
    @param[in]  in    The input samples.
    @param[in]  count Number of input samples.
    @param[in]  ratio Output rate divided by input rate.
    @param[out] out   Buffer that receives the resampled signal.
    @returns The number of samples written to `out`.
 */
template <class Sample>
unsigned resample(Sample const* in, unsigned count, double ratio, Sample* out);
Preview
resample

Resamples an audio signal to a new sample rate.

Synopsis

Declared in <resample.cpp>

template<class Sample>
unsigned int
resample(
    Sample const* in,
    unsigned int count,
    double ratio,
    Sample* out);
Return Value

The number of samples written to out.

Template Parameters

Name

Description

Sample

The sample type, usually float or short.
Parameters

Name

Description

in [in]

The input samples.

count [in]

Number of input samples.

ratio [in]

Output rate divided by input rate.

out [out]

Buffer that receives the resampled signal.

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.

Preconditions, postconditions, and exceptions together
/** Moves funds from one account to another.

    @pre `amount` is positive.
    @pre `from` and `to` are different accounts.
    @post `from` falls by `amount` and `to` rises by the same.
    @throws std::invalid_argument If an account number is unknown.
    @throws std::out_of_range If `from` cannot cover `amount`.
 */
void transfer(int from, int to, long amount);
Preview
transfer

Moves funds from one account to another.

Synopsis

Declared in <transfer.cpp>

void
transfer(
    int from,
    int to,
    long amount);
Exceptions

Name

Thrown on

std::invalid_argument

If an account number is unknown.

std::out_of_range

If from cannot cover amount.
Preconditions

  • amount is positive.

  • from and to are different accounts.

Postconditions

  • from falls by amount and to rises by the same.

Relationships

@relates ties a free function to a class, listing it among that class’s non-member functions.

Relates
/** A pixel record. */
struct pixel { int x, y; };

/** Computes the Euclidean distance between two pixels.

    @relates pixel
 */
double distance(pixel const& a, pixel const& b);
Preview
pixel

A pixel record.

Synopsis

Declared in <relates.cpp>

struct pixel;
Data Members

Name

x

y
Non-Member Functions

Name

Description

distance

Computes the Euclidean distance between two pixels.
pixel::x
Synopsis

Declared in <relates.cpp>

int x;
pixel::y
Synopsis

Declared in <relates.cpp>

int y;
distance

Computes the Euclidean distance between two pixels.

Synopsis

Declared in <relates.cpp>

double
distance(
    pixel const& a,
    pixel const& b);
Parameters

Name

Description

a

A pixel record.

b

A pixel record.

@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.

See also
/** Computes the sum of two values. */
double sum(double a, double b);

/** Computes the average of two values.

    @see @ref sum
 */
double average(double a, double b);
Preview
average

Computes the average of two values.

Synopsis

Declared in <see‐also.cpp>

double
average(
    double a,
    double b);
See Also

sum

sum

Computes the sum of two values.

Synopsis

Declared in <see‐also.cpp>

double
sum(
    double a,
    double b);

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 */.

A small regex engine using all three flags
namespace detail {
/** The compiled bytecode the matcher executes.

    @implementationdefined
 */
struct program;
}

/** A compiled regular expression.

    Holds the program built from a pattern and tests it against input
    text. Create one with `compile` rather than constructing it directly.

    @seebelow
 */
class regex
{
    detail::program* prog_;
public:
    bool match(char const* text) const;
};

struct compile_fn
{
    /** Compiles `pattern` into a regular expression. */
    regex operator()(char const* pattern) const;

    int syntax; // extra member: auto-detection skips this type
};

/** @functionobject

    The extra `syntax` member defeats auto-detection.
 */
constexpr compile_fn compile = {};

/** Exposes a regex's compiled bytecode, for debugging.

    @returns The bytecode, in an implementation-defined form.
 */
detail::program const& bytecode(regex const& re);
Preview
regex

A compiled regular expression.

Synopsis

Declared in <regex.cpp>

class regex { /* see-below */ };
Description

Holds the program built from a pattern and tests it against input text. Create one with compile rather than constructing it directly.

bytecode

Exposes a regex's compiled bytecode, for debugging.

Synopsis

Declared in <regex.cpp>

/* implementation-defined */ const&
bytecode(regex const& re);
Return Value

The bytecode, in an implementation‐defined form.

Parameters

Name

Description

re

A compiled regular expression.
compile

Compiles pattern into a regular expression.

Synopsis

Declared in <regex.cpp>

regex
compile(char const* pattern);

This function is defined as an Algorithm Function Object (AFO).
Return Value

A compiled regular expression.