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