在C++项目开发中，规范的代码文档能帮助团队快速理解项目逻辑，Doxygen是一款专门用于从带注释的源代码中生成文档的工具，支持生成HTML、PDF等多种格式的文档，适配C++等多种编程语言。
Doxygen基础安装与配置
首先需要在系统中安装Doxygen，不同系统的安装方式略有区别。Ubuntu系统可以直接通过包管理器安装，Windows系统可以下载官方安装包完成安装。
安装完成后，需要生成配置文件，在C++项目根目录执行以下命令：
doxygen -g
执行后会生成默认的Doxyfile配置文件，我们可以修改该文件中的参数来调整文档生成规则。
常用配置参数说明
| 参数名 | 作用 | 推荐值 |
|---|---|---|
| PROJECT_NAME | 设置项目名称 | 填写你的C++项目名称 |
| OUTPUT_DIRECTORY | 文档输出目录 | ./docs |
| INPUT | 需要生成文档的源代码目录 | ./src |
| FILE_PATTERNS | 匹配的文件后缀 | *.cpp *.h |
| GENERATE_HTML | 是否生成HTML文档 | YES |
C++代码注释规范
Doxygen支持多种注释风格，C++中常用的是以/**开头，以*/结尾的块注释，以及以///开头的行注释。
文件头注释
每个源文件开头可以添加文件说明注释：
/** * @file main.cpp * @brief 项目主程序入口文件 * @author 开发者名称 * @date 无年份日期 */
类注释
类的注释需要说明类的功能、使用场景等信息：
/**
* @class UserService
* @brief 用户服务类，处理用户相关的业务逻辑
* @note 该类为单例模式，通过getInstance方法获取实例
*/
class UserService {
public:
/**
* @brief 获取UserService单例实例
* @return UserService& 单例实例引用
*/
static UserService& getInstance();
/**
* @brief 根据用户ID查询用户信息
* @param userId 用户ID，类型为int
* @return std::string 用户名称，查询失败返回空字符串
* @throw std::invalid_argument 当userId小于0时抛出异常
*/
std::string getUserNameById(int userId);
};
函数注释
普通函数注释需要说明功能、参数、返回值、异常等信息：
/**
* @brief 计算两个整数的和
* @param a 第一个加数
* @param b 第二个加数
* @return int 两个加数的和
* @see subtract
*/
int add(int a, int b) {
return a + b;
}
变量与枚举注释
成员变量和枚举值也需要添加注释说明含义：
class Config {
public:
int max_connect_num; ///< 最大连接数，默认值为100
/**
* @brief 日志级别枚举
*/
enum LogLevel {
DEBUG, ///< 调试级别
INFO, ///< 信息级别
ERROR ///< 错误级别
};
};
生成文档与查看
完成配置文件修改和代码注释后，在项目根目录执行以下命令即可生成文档：
doxygen Doxyfile
生成完成后，进入配置的OUTPUT_DIRECTORY目录下的html文件夹，打开index.html即可查看生成的HTML文档，文档中会包含所有的类、函数、变量的说明，结构清晰，方便查阅。
常见问题处理
- 如果生成的文档中没有显示注释内容，需要检查注释格式是否符合Doxygen规范，以及配置文件中
EXTRACT_ALL参数是否设置为YES，该参数开启后会提取所有代码元素的注释，即使没有完整标注也会尝试提取。 - 如果需要生成PDF文档，需要先安装latex环境，然后将配置文件中的
GENERATE_LATEX设置为YES，生成latex文件后再编译为PDF。 - 注释中如果有特殊字符，比如
<、>，在代码中不需要额外转义，Doxygen会自动处理，但如果是在注释中说明HTML标签，需要按照规则转义书写。
Doxygen的注释标签还有很多，比如
@param[in]表示输入参数，@param[out]表示输出参数，@deprecated标记已废弃的接口，开发者可以根据实际需求选择使用对应的标签，让文档更加详细准确。