Introduction to LPCDoc

LPCDoc is a documentation format for LPC (Lars Pensjö C). It defines a structured way to annotate LPC source code with standardized comments, facilitating the generation of comprehensive and user-friendly documentation.

Commenting Conventions

LPCDoc comments, known as “doc comments,” should be placed immediately before the code they describe. Each comment must start with a /** sequence to be recognized as an LPCDoc annotation. For example:

/**
 * This is a description of the foo function.
 */
void foo() {
    // Function implementation
}

The simplest documentation includes a description of the function, variable, or function. Additional details can be provided using LPCDoc tags.

LPCDoc Tags

LPCDoc utilizes various tags to structure documentation. Some of the most commonly used tags include:

• @param {type} name - Documents a function parameter.
• @returns {type} - Documents the return value of a function.
• @example - Provide example code snippets to show usage.
• @throws reason - Documents a reason this function could throw().
• @errors reason - Documents a reason this function might error().
• @deprecated - Indicates that a function is deprecated.
• @author name - Identifies the author of an item.

Example

/**
 * Parses a configuration file.
 *
 * @param {string} filepath - The path to the configuration file.
 * @returns {mapping} The parsed configuration.
 * @throws If the configuration file was not found.
 * @errors If the configuration was malformed.
 * @example
 * mapping config = parse_config("/data/config/seasons.cfg");
 *
 * // ([
 * //   "spring": 0,
 * //   "summer": 365,
 * //   "autumn": 0,
 * //   "winter": 0,
 * // ])
 */
mapping parse_config(string filepath) {
    // Implementation
}