C++ Doxygen 注释规范详解

Doxygen 是 C++ 中最常用的文档生成工具，以下是完整的注释规范指南。

1. 基本注释格式

1.1 三种注释风格

/// 单行注释（推荐）
/** 多行注释块 */
/*! 另一种多行注释 */

1.2 推荐的文件头注释

/**
 * @file    MyClass.h
 * @brief   简要描述文件功能
 * @author  作者名
 * @date    创建日期
 * @version 版本号
 * 
 * @details 详细描述文件功能和使用方法
 * 
 * @copyright 版权信息
 */

2. 函数注释规范

2.1 基本函数注释

/**
 * @brief 计算两个数的和
 * 
 * @param a 第一个加数
 * @param b 第二个加数
 * @return int 两个数的和
 * 
 * @note 此函数不检查溢出
 * @warning 参数不能为负数
 * @see subtract(), multiply()
 */
int add(int a, int b) {
    return a + b;
}

2.2 重载函数注释

/**
 * @brief 计算两个浮点数的和
 * @overload
 */
double add(double a, double b);

2.3 模板函数注释

/**
 * @brief 泛型加法函数
 * 
 * @tparam T 数值类型，必须支持+操作符
 * @param a 第一个加数
 * @param b 第二个加数
 * @return T 两个数的和
 */
template<typename T>
T add(T a, T b) {
    return a + b;
}

3. 类注释规范

3.1 类定义注释

/**
 * @brief 表示二维空间中的点
 * 
 * 这个类提供了二维坐标系中点的基本操作，
 * 包括移动、计算距离等功能。
 */
class Point {
public:
    /**
     * @brief 默认构造函数
     * @post 创建坐标为(0,0)的点
     */
    Point();
  
    /**
     * @brief 带参数构造函数
     * @param x X坐标
     * @param y Y坐标
     */
    Point(double x, double y);
  
    /// @brief 获取X坐标
    double getX() const;
  
    /// @brief 获取Y坐标  
    double getY() const;
  
private:
    double x_; ///< X坐标值
    double y_; ///< Y坐标值
};

3.2 继承关系注释

/**
 * @brief 表示三维空间中的点
 * @extends Point
 */
class Point3D : public Point {
    // ...
};

4. 枚举和结构体注释

4.1 枚举注释

/**
 * @brief 颜色枚举定义
 */
enum class Color {
    RED,    ///< 红色
    GREEN,  ///< 绿色  
    BLUE    ///< 蓝色
};

4.2 结构体注释

/**
 * @brief 表示人员信息的数据结构
 */
struct Person {
    std::string name;     ///< 姓名
    int age;             ///< 年龄
    std::string address; ///< 地址
};

5. 命名空间注释

/**
 * @brief 数学工具命名空间
 * 
 * 包含各种数学计算相关的函数和类
 */
namespace MathUtils {
    // ...
}<

6. 常用Doxygen命令详解

6.1 基本命令

命令	说明	示例
`@brief`	简要描述	`@brief 计算平方根`
`@details`	详细描述	`@details 使用牛顿迭代法...`
`@param`	参数说明	`@param x 输入数值`
`@return`	返回值说明	`@return 计算结果`
`@tparam`	模板参数	`@tparam T 元素类型`

6.2 高级命令

/**
 * @brief 复杂的函数示例
 * 
 * @param[in] input 输入参数（只读）
 * @param[out] output 输出参数（写入结果）
 * @param[in,out] inout 输入输出参数
 * 
 * @return 操作结果
 * @retval 0 成功
 * @retval -1 失败
 * 
 * @throw std::invalid_argument 当输入无效时
 * @exception std::runtime_error 运行时错误
 * 
 * @pre input != nullptr
 * @post output 包含有效结果
 * 
 * @note 此函数线程安全
 * @warning 需要手动释放内存
 * @bug 已知问题描述
 * @todo 待完成功能
 * 
 * @deprecated 使用新函数代替
 * 
 * @see relatedFunction()
 * @cite 参考文献
 * 
 * @code
 * // 使用示例
 * int result = function(input, output);
 * @endcode
 */
int function(const int* input, int* output);

6.3 条件编译注释

#if defined(DEBUG)
/**
 * @brief 调试版本特有的函数
 * @debug 仅在调试模式下可用
 */
void debugFunction();
#endif

7. 格式化标记

7.1 文本格式化

/**
 * @brief 格式化示例
 * 
 * 这是普通文本
 * 
 * - 项目符号1
 * - 项目符号2
 * 
 * 1. 编号列表1
 * 2. 编号列表2
 * 
 * 这是<b>粗体</b>文本
 * 这是<em>斜体</em>文本
 * 
 * 行内代码：@c variableName
 * 代码块：
 * @code{.cpp}
 * int x = 42;
 * std::cout << x << std::endl;
 * @endcode
 * 
 * 数学公式：
 * 行内公式 @f$ E = mc^2 @f$
 * 块公式：
 * @f[
 *   \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
 * @f]
 * 
 * 链接：<a href="http://example.com">链接文本</a>
 */

8. 实际完整示例

8.1 完整的类示例

/**
 * @file    Vector.h
 * @brief   动态数组容器实现
 * @author  Developer
 * @date    2024-01-01
 * @version 1.0
 */

#ifndef VECTOR_H
#define VECTOR_H

#include <stdexcept>

/**
 * @brief 泛型动态数组容器
 * @tparam T 数组中元素的类型
 * 
 * 这个类提供了类似std::vector的功能，但实现更简单。
 * 支持动态扩容、随机访问等操作。
 */
template<typename T>
class Vector {
public:
    /**
     * @brief 默认构造函数
     * @post 创建容量为10的空向量
     */
    Vector();
  
    /**
     * @brief 带初始容量的构造函数
     * @param capacity 初始容量
     * @throw std::invalid_argument 如果capacity <= 0
     */
    explicit Vector(size_t capacity);
  
    /**
     * @brief 拷贝构造函数
     * @param other 要拷贝的向量
     */
    Vector(const Vector& other);
  
    /**
     * @brief 析构函数
     */
    ~Vector();
  
    /**
     * @brief 在末尾添加元素
     * @param value 要添加的值
     * @post 如果容量不足，自动扩容
     */
    void push_back(const T& value);
  
    /**
     * @brief 获取指定位置的元素
     * @param index 元素索引（0-based）
     * @return const T& 元素的常量引用
     * @throw std::out_of_range 如果index >= size()
     */
    const T& at(size_t index) const;
  
    /**
     * @brief 获取向量当前大小
     * @return size_t 元素数量
     */
    size_t size() const;
  
    /**
     * @brief 获取向量容量
     * @return size_t 当前容量
     */
    size_t capacity() const;
  
    /**
     * @brief 检查向量是否为空
     * @return bool 如果为空返回true
     */
    bool empty() const;

private:
    T* data_;           ///< 数据数组指针
    size_t size_;       ///< 当前元素数量
    size_t capacity_;   ///< 当前容量
  
    /**
     * @brief 扩容向量
     * @param new_capacity 新的容量
     * @post 容量至少变为原来的2倍
     */
    void resize(size_t new_capacity);
};

#endif

9. Doxygen配置文件建议

在 Doxyfile中设置以下重要选项：

PROJECT_NAME           = "My Project"
PROJECT_NUMBER         = 1.0
OUTPUT_DIRECTORY       = docs/
INPUT                  = src/
RECURSIVE              = YES
FILE_PATTERNS          = *.h *.hpp *.cpp *.c
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
SOURCE_BROWSER         = YES
GENERATE_LATEX         = NO
GENERATE_HTML          = YES

10. 最佳实践

一致性：整个项目保持统一的注释风格
及时更新：代码修改时同步更新注释
简明扼要：注释要简洁明了，避免冗长
英文优先：国际项目建议使用英文注释
版本控制：重要的API变更要更新版本信息

通过遵循这些规范，可以生成专业、易读的API文档，提高代码的可维护性。