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 thedoc
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 |
Javadoc-style comments |
|
C, C++, etc. |
Doxygen |
Doxygen-style comments |
|
JavaScript |
JSDoc |
- |
|
C# |
XML Documentation Comments |
- |
|
Rust |
Rustdoc |
- |
|
Swift |
Swift Markup |
- |
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.