Documenting the Code

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, a doc comment is a block between /** and */ placed above a class, function, or field declaration. Sequential ///-comments are a common alternative, especially for single-line blocks. Both styles can appear side by side in the same file:

A struct, its members, and a function, mixing /** and ///
/** 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
{
    /// The person's full name.
    char const* name;

    /// The person's age in years.
    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);
Preview·Rendered output
person

The main information about a person

Synopsis

Declared in <person.cpp>

struct person;
Description

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.

Data Members

Name

Description

age

The person's age in years.

name

The person's full name.
Non-Member Functions

Name

Description

greet

A function to greet a person
person::age

The person's age in years.

Synopsis

Declared in <person.cpp>

int age;
person::name

The person's full name.

Synopsis

Declared in <person.cpp>

char const* name;
greet

A function to greet a person

Synopsis

Declared in <person.cpp>

void
greet(person const& p);
Description

This function takes a person and prints a greeting message.

Parameters

Name

Description

p

The person to greet

Each doc comment in the example above starts with a brief sentence, optionally followed by a detailed description. Most doc comments contain those two sections; you can also mark them explicitly with @brief and @details.

Doc comments can also carry special commands like @param, @returns, or @throws that attach structured information to the declaration. MrDocs supports most commands you would already use in a Javadoc or Doxygen comment. The Commands Reference lists every command MrDocs understands, grouped by category.

Documentation Comment Formats

The format MrDocs reads goes back to Java’s doc tool and spread from there. Each ecosystem that picked it up kept the same /** …​ */ shape and added its own conventions.

  • Javadoc started the convention with Java. Its official specification calls them Documentation Comments, usually shortened to "doc comments"; in practice many developers know them as Javadoc-style comments.

  • Doxygen brought the same syntax to C, C++, and other languages. The docs call them comment blocks but also call out the Javadoc lineage for readers coming from Java.

  • JSDoc brought the same idea to JavaScript. Developers there call them JSDoc comments, following the tradition of naming the form 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

-

  • The original term, coming from Java, is doc comments; later tools followed the same convention.

  • Many communities still call them after the tool: Javadoc-style comments, Doxygen-style comments, JSDoc comments.

  • MrDocs reads the same /** …​ */ shape, so a doc comment that compiles for Doxygen typically works here without changes.

Parsing Algorithm

MrDocs uses the same two-phase parsing model as the CommonMark specification. It adds a pre-step to extract the text from the comment markers, and recognizes some MrDocs-specific commands alongside the standard CommonMark syntax.

graph LR classDef input fill:#D1E8FF,stroke:#005CFF,stroke-width:2; classDef common fill:#FFF5D1,stroke:#FFA500,stroke-width:2; classDef mrdocs fill:#F3D1FF,stroke:#8000C0,stroke-width:2; classDef output fill:#D1FFD1,stroke:#008000,stroke-width:2; PRE["Pre-step
strip markers,
fix indentation"] B1["Phase 1
group lines
into blocks"] B2["Metadata blocks
@param, @returns…"] I1["Phase 2
parse inline
elements"] I2["Inline commands
@ref, @copydoc…"] DOC["Structured comment
on the symbol"] PRE --> B1 --> I1 --> DOC B1 -. extends .-> B2 I1 -. extends .-> I2 class B1,I1 common class PRE,B2,I2 mrdocs class DOC output
Figure 1. Doc-comment parsing pipeline

Pre-step: extract text from the comment

Source comments arrive wrapped in markers: /** …​ */ with optional leading * continuation characters, or runs of /// and //! lines. MrDocs strips those markers and normalizes the leading indentation. The result is plain text, ready for the rest of the algorithm.

Phase 1: group lines into blocks

MrDocs walks the lines in order and groups them into blocks: paragraphs, lists, fenced and indented code blocks, block quotes, and headings.

MrDocs adds one more family: metadata blocks, introduced by commands like @brief, @param, @returns, @throws, @par, or @code / @endcode. Each one supplies structured information for the declaration: a parameter description, a return value, a named section, a code example. Parsing is the same as for any other block. The difference comes later, when MrDocs attaches each metadata block to the right field on the symbol’s record.

Phase 2: parse the contents of each block

Once the block structure is fixed, MrDocs parses each block’s content for inline elements, such as emphasis, code spans, and links.

On top of those CommonMark inlines, MrDocs recognizes extra inline commands: cross-references like @ref, copy directives like @copydoc, Doxygen-style formatting commands such as @a, @b, and @c, and inline math. The Inline Commands page lists them all.