cpp-api-documentation（CPP API 文档）

API Documentation

Instructions for AI coding agents on adding Doxygen-compatible documentation comments to C++ header files.

[!NOTE] This skill is for documenting header files only. Do NOT create new resource files (e.g., Doxyfile, scripts, README).

• 1. Benefits
• 2. Principles
• 3. Patterns

- 3.1. File Documentation - 3.2. Namespace Documentation - 3.3. Class Documentation - 3.4. Function/Method Documentation - 3.5. Cross-References - 3.6. Member Documentation - 3.7. Enumerations - 3.8. Grouping and Modules - 3.9. Inheritance - 3.10. Formula Documentation

• 4. Workflow
• 5. Style Guide
• 6. Template

- 6.1. File Header Template - 6.2. Namespace Template - 6.3. Class Template - 6.4. Function Template - 6.5. Member Variable Template - 6.6. Enumeration Template - 6.7. Module/Group Template - 6.8. Formula Template

• 7. References

1. Benefits

• Discoverability Well-documented APIs enable developers to quickly understand and use components without reading implementation details.
• Maintainability Documentation embedded in source code stays synchronized with implementation, reducing drift between code and documentation.
• Traceability Documentation comments serve as living specifications, keeping API contracts synchronized with implementation.

2. Principles

Effective API documentation follows these core principles.

• Complete Document all public APIs including classes, functions, parameters, return values, and exceptions. Private implementation details may be omitted.
• Contextual Documentation provides context about usage patterns, performance characteristics, and thread safety guarantees.
• Consistent Use a uniform style, format, terminology and structure throughout the API documentation using the patterns defined in this skill.
• Concise Use clear, brief descriptions. Avoid redundant information that restates what is obvious from the signature.
• Concrete Provide specific details about behavior, edge cases, and error conditions rather than vague statements.
• Convenient Documentation should be easy to access and navigate, integrated with development tools and workflows.
• Accurate Documentation must match the actual behavior. Update documentation whenever the implementation changes.
• Actionable Include usage examples, preconditions, postconditions, and error handling to help developers use the API correctly.

3. Patterns

3.1. File Documentation

File-level documentation provides context for the entire header file.

• Purpose Describes the file's role in the project architecture.
• Author Identifies the original author(s) of the file.
• License Specifies the licensing terms (typically SPDX identifier).

3.2. Namespace Documentation

Namespace-level documentation describes the purpose of the namespace.

• Brief A one-line summary of what the namespace contains.
• Details Extended description of the namespace's role and contents.

3.3. Class Documentation

Class-level documentation describes the abstraction.

• Brief A one-line summary of what the class represents.
• Details Extended description of responsibilities, invariants, and usage patterns.
• Template Parameters For template classes, document each template parameter's purpose and constraints.

3.4. Function/Method Documentation

Function-level documentation describes the contract.

• Brief A one-line summary of what the function does.
• Parameters Document each parameter with @param including direction ([in], [out], [in,out]).
• Return Value Document the return value with @return or @retval for specific values.
• Exceptions Document thrown exceptions with @throws or @exception.
• Warnings Use @warning for critical warnings about misuse.
• Notes Use @note for important information.
• Preconditions Document preconditions with @pre.
• Postconditions Document postconditions with @post.
• Code Examples Use @code and @endcode blocks for usage examples.

3.5. Cross-References

Cross-references link related documentation.

• See Also Use @see to reference related functions, classes, or external resources.

3.6. Member Documentation

Member-level documentation clarifies data semantics.

• Inline Comments Use ///< description for trailing inline documentation.
• Block Comments Use /// description for preceding documentation.

3.7. Enumerations

Enumerations document possible values and their meanings.

• Values Document each enumerator with a brief Inline Comments description.

3.8. Grouping and Modules

Organize related elements into logical groups.

• Defgroups Use @defgroup to create named documentation modules.
• Ingroups Use @ingroup to add elements to existing groups.
• Memberof Use @memberof for explicit class membership.

3.9. Inheritance

Class hierarchies and inherited documentation.

• Base Classes Document inherited classes with @copydoc or @copybrief to reuse base class documentation.

3.10. Formula Documentation

Mathematical formulas using LaTeX syntax for algorithms and technical documentation.

• Inline Formulas Use \f$..\f$ for formulas that appear within running text (opens LaTeX math mode).
• Inline Text-Mode Formulas Use \f(...\f) for LaTeX elements that don't require explicit math mode (e.g., logos like \LaTeX).
• Displayed Formulas Use \f[...\f] for centered, unnumbered equations on separate lines.
• Environment Formulas Use \f{environment}{...\f} for specific LaTeX environments (e.g., eqnarray*, align).
• MathJax Alternative Enable USE_MATHJAX in Doxyfile for client-side formula rendering without requiring LaTeX installation.
• Custom Macros Use FORMULA_MACROFILE configuration to define reusable LaTeX commands with \newcommand.

4. Workflow

[!IMPORTANT] Do NOT create Doxyfile, scripts, or other resource files. Only modify header files.

1. Identify Identify undocumented or poorly documented public APIs in header files (e.g., src/<module>/<header>.hpp).
2. Add Documentation Comments Add Doxygen-compatible documentation comments directly to header files following the templates below.
3. Documentation Coverage Requirements Include comprehensive documentation for:

- All public classes, structs, and enums - All public and protected member functions - All function parameters and return values - All template parameters - Exception specifications - Thread safety guarantees when applicable - Complexity guarantees for algorithms

1. Apply Templates Structure all documentation using the template patterns below.
2. Review Review documentation for accuracy and readability.

5. Style Guide

Doxygen supports multiple comment styles. Use the Javadoc style for consistency.

• Language Write documentation in clear, concise English. Use present tense for descriptions ("Returns the sum" not "Will return the sum").
• Line Length Keep documentation lines under 100 characters for readability.
• Block Comments Use /**... */ for multi-line documentation blocks. Each line within the block should start with *.
• Comment Style Prefer /// for single-line documentation and /** */ for multi-line documentation blocks. Use Javadoc-style commands (@param, @return) rather than Qt-style (\param, \return).
• Brief Descriptions Use @brief for explicit brief descriptions.
• Detailed Descriptions Add detailed descriptions after the brief, separated by a blank line or using @details.
• Parameter Direction Always specify parameter direction using [in], [out], or [in,out] for clarity.
• Code Examples Use @code and @endcode blocks for usage examples within documentation.
• Cross-References Use @see to reference related functions, classes, or external resources.
• Warnings and Notes Use @note for important information and @warning for critical warnings.
• Deprecation Mark deprecated APIs with @deprecated including migration guidance.
• TODO Items Use @todo for planned improvements visible in generated documentation.
• Order of Tags Follow this order for function documentation: @brief @details (if needed) @tparam (for templates) @param @return @throws @pre @post @note @warning @see @deprecated

6. Template

Use these templates for new documentation. Replace placeholders with actual values.

6.1. File Header Template

[!NOTE] Place the @file block after the include guard (#pragma once or #ifndef/#define). This ensures the documentation is parsed once along with the declarations it describes and keeps preprocessor directives separate from API documentation.

#pragma once

/**
 * @file <filename>.hpp
 * @brief One-line description of the file's purpose.
 *
 * Detailed description of the file's contents and design decisions.
 *
 * @author <author_name>
 * @copyright Copyright (c) <year> <organization>
 * @license SPDX-License-Identifier: <license_identifier>
 */

6.2. Namespace Template

/**
 * @brief One-line description of namespace contents.
 *
 * Detailed description of the namespace's role, the types of
 * components it contains, and how they relate to each other.
 */
namespace namespace_name {

// Namespace contents

}  // namespace namespace_name

6.3. Class Template

/**
 * @brief One-line description of the class.
 *
 * Detailed description of the class responsibility, key invariants,
 * and usage patterns.
 *
 * @tparam T Description of template parameter and constraints.
 *
 * @note Thread safety: Describe thread safety guarantees.
 *
 * @see RelatedClass
 *
 * @code
 * ClassName<int> obj;
 * obj.method(param);
 * @endcode
 */
template <typename T>
class ClassName
{
  // ...
};

6.4. Function Template

/**
 * @brief One-line description of what the function does.
 *
 * Detailed description including algorithm details and edge cases.
 *
 * @param[in] param1 Description of the input parameter.
 * @param[out] param2 Description of the output parameter.
 * @param[in,out] param3 Description of bidirectional parameter.
 *
 * @return Description of the return value.
 * @retval specific_value Meaning of this specific return value.
 *
 * @throws std::invalid_argument If param1 is invalid.
 * @throws std::runtime_error If operation fails.
 *
 * @pre Preconditions that must be met before calling.
 * @post Postconditions guaranteed after successful execution.
 *
 * @note Important information for users.
 * @warning Critical warnings about potential misuse.
 *
 * @see relatedFunction()
 *
 * @code
 * auto result = functionName(input, output);
 * @endcode
 */
ReturnType functionName(const InputType& param1, OutputType& param2);

6.5. Member Variable Template

class ClassName
{
private:
  int count_;       ///< Number of items currently stored.
  bool is_valid_;   ///< Whether the object is in a valid state.

  /// Description for simple members.
  int simple_member_;

  /**
   * @brief Buffer for temporary storage.
   *
   * Detailed explanation of the member's purpose and
   * synchronization requirements.
   */
  std::vector<char> buffer_;
};

6.6. Enumeration Template

/**
 * @brief Description of what this enumeration represents.
 *
 * Detailed description of the enum's purpose and usage context.
 */
enum class EnumName
{
  Success,     ///< Operation completed successfully.
  Error,       ///< Operation failed with an error.
  Pending,     ///< Operation is still in progress.
  NotFound     ///< Requested item was not found.
};

6.7. Module/Group Template

/**
 * @defgroup module_name Module Display Name
 * @brief One-line description of the module.
 *
 * Detailed description of the module purpose and components.
 *
 * @{
 */

// Classes and functions belonging to this group

/** @} */  // End of module_name

6.8. Formula Template

/**
 * @brief Calculates the Euclidean distance between two points.
 *
 * The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is
 * \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.
 *
 * For complex equations, use displayed formulas:
 * \f[
 *   d = \sqrt{\sum_{i=1}^{n}(p_i - q_i)^2}
 * \f]
 *
 * Multi-line equations using eqnarray environment:
 * \f{eqnarray*}{
 *   E &=& mc^2 \\
 *   F &=& ma
 * \f}
 *
 * @param[in] x1 X-coordinate of the first point.
 * @param[in] y1 Y-coordinate of the first point.
 * @param[in] x2 X-coordinate of the second point.
 * @param[in] y2 Y-coordinate of the second point.
 *
 * @return The Euclidean distance \f$d \geq 0\f$.
 */
double distance(double x1, double y1, double x2, double y2);

7. References

• Doxygen Manual guide.
• Doxygen Commands reference.
• Doxygen Configuration reference.
• Doxygen Formulas reference.
• Google C++ Style Guide Comments section.