The code should be documented with the Doc Comment format, also informally known as "javadoc" format or Doxygen-style comments.

In its most basic form, these are usually comment blocks between /** and */ placed above a class, function, or field declaration:

/** The main information about a person

    This class represents a person with
    a name and an age. This is the
    information about a person that
    we need to store in our system.
struct person
    std::string name;
    int age;

/** A function to greet a person

    This function takes a person and
    prints a greeting message.

    @param p The person to greet
void greet(person const& p);

A common alternative is to use ///, especially for single-line comments:

/// A constant representing the number of hours in a day
static constexpr int hours_in_day = 24;

Both the class and the function above have doc comments with a brief sentence and a detailed description. Most doc comments will contain these two sections, which could also be explicitly marked with @brief and @details commands.

Doc comments can also contain a number of special commands such as @param that are used to document the parameters of a function.


The following commands can be used to format the text in the doc comments:




Formats the text in italics


Formats the text in italics


Formats the text in italics


Formats the text in bold


Formats the text in bold