Commands

The code should be documented with the Doc Comment format, also informally known as Javadoc-style 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 many special commands, such as @param, that are used to document the parameters of a function. Mr. Docs supports most commands commonly used in Javadoc and Doxygen comments.

Documentation Comment Formats

The documentation format used by MrDocs has its roots in earlier tools and languages. It is based on writing structured comments directly in the source code, which are then parsed to generate API reference documentation.

  • Origins: Javadoc: The format originated with Java and the doc tool. The official specification consistently calls these comments Documentation Comments, often abbreviated as "doc comments". In practice, many developers also refer to them as Javadoc-style comments due to their close association with the doc tool.

  • Doxygen: When Doxygen was created to support C, C++, and other languages, it adopted a similar comment style. In its documentation section about this comment style, Doxygen calls these comments comment blocks, but also explains them as Javadoc style comments for users familiar with the Java ecosystem. This established the convention of using the same recognizable syntax (/** …​ */) across different ecosystems.

  • JSDoc: For JavaScript, the JSDoc tool introduced the same concept. Developers usually refer to them as JSDoc comments, again following the tradition of naming the comments after the tool.

Other ecosystems have adopted similar approaches and comment styles, sometimes with different syntax:

  • C#: XML documentation comments (/// …​)

  • Rust: doc comments (/// …​ and //! …​)

  • Swift: markup-based documentation comments (/// …​)

Language Tool Official Term Common Term

Java

Javadoc

Documentation comments

Javadoc-style comments

C, C++, etc.

Doxygen

Comment blocks

Doxygen-style comments

JavaScript

JSDoc

JSDoc comments

-

C#

XML Documentation Comments

XML documentation comments

-

Rust

Rustdoc

Doc comments

-

Swift

Swift Markup

Markup documentation comments

-

Briefly summarizing the table above:

  • The original term, from Java, is doc comments. Other tools follow a similar convention.

  • Many tools and communities prefer to call them after the tool name, e.g. Javadoc-style comments, Doxygen-style comments, or JSDoc-style comments.

  • MrDocs follows this tradition by supporting a familiar syntax that developers across ecosystems already recognize.