Pure Programmer
Blue Matrix

Cluster Map

Documentation

Every program describes how to accomplish some task in the language of mathematics and logic. While high level languages help us to express programming concepts easily and clearly, they are often not the best way to explain the abstract concepts involved. This is where programming documentation comes to the rescue. Documentation in the form of program comments interspersed in the source code are a means to explain in plain English the expected workings of a program and the high level concepts involved. They are a way to include information that is not obvious or clear in the programming statements themselves.

In this site we will use a standard block of comments at the beginning of each file to explain the purpose of the program in the file. We will include the program author, the date that the program was written and any updates that were made. This last use of comments to document the update history is one that should only be used for programs that are not under source code control. For complex multi-file programs a [[source code control system]] will be a necessity and will perform the task of managing the update history of files.

Basic comments take two forms: single-line and multiple-line. Single-line comments begin with a double slash (//) and continue to the end of the current line. They can start at the beginning of the line or anywhere in the middle of a line. Multi-line comments may begin anywhere using the comment start symbol (/*) and continue until the comment end symbol (*/). All characters in the comment are ignored and not considered to be executable program content.

The following are examples of comments.

// This is a single line comment

/* This is an example
   of a multi-line comment */

Each program file, class or function/method should have a comment preceding it that describes the purpose and typical usage of the item being documented. Comments should document the high-level behavior and not get involved in the specifics of the current implementation. Implementation details can change but the interface described by the comment should rarely change. It also helps to know how the program, class or function/method is intended to perform when the code itself is found to have a bug. The following is an example of what a program file comment might look like.

/*********************************************************************
 * This program computes ...
 *
 * Copyright © 2023 Richard Lesh.  All rights reserved.
 ********************************************************************/

Modern C++ Documentation

Modern C++ documentation has two layers:

  1. Human-facing guides: README, tutorials, architecture notes, examples
  2. API/reference docs: generated from source using Doxygen-style comments

What Should Be Documented

Modern C++ documentation should describe:

This aligns better with how modern C++ libraries are read and maintained. C++ doesn't have a special documentation syntax for documenting APIs but there is a popular tool called Doxygen that can read specially formatted C++ comments to generate HTML API documentation automatically.

Doxygen Comments

Doxygen supports Javadoc-style comment blocks such as /** ... */, Qt-style /*! ... */, and line forms like /// or //!. It also supports brief and detailed descriptions, plus commands like @param and @return.

For example a Doxygen comment for a function might look like this:

/**
 * @brief Computes the area of a circle.
 *
 * Uses the standard formula pi * r^2.
 *
 * @param radius Radius of the circle in meters. Must be non-negative.
 * @return Area in square meters.
 * @throws std::invalid_argument if radius is negative.
 */
double circleArea(double radius);

This is a typical Doxygen documentation block. The comment begins with /** unlike normal comments (// or /* */), this style signals to documentation tools that the text inside should be parsed and included in generated API documentation.

The comment is placed immediately before the function declaration, which tells Doxygen that the documentation applies to that function.

The @brief tag provides a short one-sentence description of the function.

Most documentation systems display the brief description in:

The brief description should explain what the function does, not how it works internally.

After the brief description line, you can include additional explanatory text.

This section may describe:

Doxygen treats this as the detailed description of the function.

The @param tag documents each formal parameter of the function.

Good parameter documentation usually explains:

Each function parameter should normally have its own @param entry.

The @return tag explains what value the function returns.

It should describe:

Even if the return type is obvious from the code, describing the meaning of the result is helpful for readers.

The @throws tag documents exceptions that the function may throw.

It should include:

This helps programmers understand the error conditions that must be handled when calling the function.

Structured comments like this serve several purposes:

  1. Readable source code documentation
  2. Automatically generated API reference manuals
  3. Improved IDE tooltips and code navigation
  4. Clear documentation of interface contracts

Tools such as Doxygen can scan these comments and generate HTML, PDF, or other forms of documentation directly from the source code.

Classes, enumerations and templates can also have Doxygen comments placed before them. For example:

Class Example

/**
 * @brief Represents a bank account with a running balance.
 *
 * Instances are not thread-safe.
 */
class Account {
public:
    /**
     * @brief Deposits money into the account.
     *
     * @param amount Amount to deposit. Must be positive.
     */
    void deposit(double amount);

    /**
     * @brief Returns the current balance.
     *
     * @return Current balance in dollars.
     */
    [[nodiscard]] double balance() const noexcept;
};

Enumeration Example

/**
 * @brief States a task can be in during execution.
 */
enum class TaskState {
    pending,   ///< Task has not started yet.
    running,   ///< Task is currently executing.
    complete,  ///< Task finished successfully.
    failed     ///< Task ended with an error.
};

Template Example

/**
 * @brief Returns the larger of two values.
 *
 * @tparam T A type that supports operator<.
 * @param a First value.
 * @param b Second value.
 * @return The larger of a and b.
 */
template 
const T& maxValue(const T& a, const T& b);

References