Skip to content

Documentation

Jump to bottom
Joël R. Langlois edited this page Jan 12, 2026 · 10 revisions

Philosophy

Though your code should be relatively self-documenting, at least document all of your complex functions. Jumping into a well documented application codebase and library is helpful and appreciated, especially when the flow is new or simply not obvious!

System

Headers

Use Doxygen for header documentation.

Implementations

For implementation file documentation (eg: in .cpp and .mm files), use basic comments to explain a complex or non-obvious piece of code.

Style

  • Use two asterisks to delineate the beginning of a class, function, method or variable comment.
  • Use Javadoc-style.
    • Use the @ symbol for commands.

Rules

  • Only one space must follow the /**.
  • The initial sentence must be a summary of the intent (an implied @brief), or a well described intent in and of itself.
  • This summary must be written in normal sentence case and end with a period.
  • The summary must be written on the same line as the /**.
  • If the comment is easy to read on one line, put it on one line!
  • Otherwise, if the comment spans multiple lines, the closing */ must be on its own line.
  • Use simple newlines for separator lines.
  • Do not use a symbol to represent the beginning of a new line!

Examples

/** Does stuff and things.
 
    This function is very important for... reasons.
*/
void foo();
/** A double-precision floating point representation of pi.
 
    @see https://en.wikipedia.org/wiki/Pi
*/
static const double pi = 3.141592654;
/** @see https://www.google.ca */
void bar();

Command Rules

Do not redundantly specify default commands.

For example, do this to automatically make use of @brief and @details:

/** Does stuff and things
 
    Does an important bunch of stuff and things.
*/
void foo();

Do not specify the following commands, unless there's something legal telling you otherwise (use your best judgement!):

Only use these commands in your code:

Clone this wiki locally