Document your code

Motivation

The document you are reading now was generated using Doxygen. It follows in the tradition of literal programming, the goal of which is to keep documentation in the source code, when practical. This way, the documentation will not be outdated or unmaintained.

Commenting interfaces

Concise comments are prefered, as long as the explanation is correct, is not open to interpretation and does not assume extensive knowledge of other parts of the system.

By interface, we mean all content of a header file which is available from a C++ source file, and could result in compile errors if removed. When you comment a header file, you need to take care of a few, minor things in order to produce readable documentation using Doxygen. The basic guidelines for this project are:

• When commenting part of an interface, use one slash followed by two asterisks, followed by a line break and then the actual comment with an asterisk and a space aligned to the first asterisk in the opening line. The first sentence you write, terminated by a period, will be the brief description. After that, you can write a longer, more detailed description. The brief description will be shown in overviews, so it should be no more than a single line. It is possible to document virtually all parts of an interface, so it is not limited to classes.

Example:

/** Takes care of displaying the map and game-data on the screen.
  
 * The display is divided into two main sections: the game area,
 * which displays the tiles of the game board, and units on them,
 * and the side bar, which appears on the right hand side.
 * The side bar display is divided into three sections.
 */
class display
{
   ...
};

• It is also possible to document symbols on the same line by using a slash followed by two asterisks and a left angular bracket:

enum ADDON_TYPE {
    ADDON_SP_CAMPAIGN,  /**< Single-player campaign. */
    ADDON_SP_SCENARIO,  /**< Single-player scenario. */
    ADDON_MP_CAMPAIGN,  /**< Multiplayer campaign. */
    ADDON_MP_SCENARIO,  /**< Multiplayer scenario. */
};

• Do not refer to multiple objects of the type "Manager" as "Managers" or "manager". Instead, say "Manager objects". Doxygen will automatically link to class documentation whenever it finds class names in comments, but will not do so if you do not use their proper names.
• Many Doxygen commands can be used in comments to enhance the generated documentation and structure the comments.
• There is a balance between readable autogenerated documentation and readable code, so beware of overdoing it.

Example:

/** @param a    an integer dividend
 * @param b an integer divisor, which must not be zero
 * @returns a / b
  
 * @pre b != 0
 * @post divide' = a / b
  
 * @throws std::runtime_error
 * @todo this has not been peer reviewed yet
 */
int divide(int a, int b)
{
    return a / b;
}