使用Doxygen可高效生成C++项目API文档。首先通过doxygen -g Doxyfile生成配置文件，设置PROJECT_NAME、OUTPUT_DIRECTORY、INPUT等关键参数，启用HTML输出和递归扫描。接着在代码中编写符合Qt或JavaDoc风格的注释，使用@brief、@param、@return等命令描述函数与类。执行doxygen Doxyfile生成文档，可在docs/html/index.html查看结果，支持类图与调用关系图（需Graphviz）。建议将doc: doxygen Doxyfile加入Makefile或CI/CD流程，实现自动化更新，确保文档与代码同步。
使用Doxygen为C++项目生成API文档是一个高效且规范的方式，尤其适合中大型项目。Doxygen能从源码注释中提取信息，自动生成结构清晰的HTML、LaTeX、PDF等格式的文档。以下是具体操作步骤和实用技巧。
配置Doxyfile文件
Doxygen通过一个名为Doxyfile的配置文件控制文档生成行为。首先在项目根目录下运行以下命令生成默认配置：
doxygen -g Doxyfile
这会创建一个初始的Doxyfile。你可以编辑它来定制输出。关键配置项包括：
立即学习“C++免费学习笔记（深入）”；
- PROJECT_NAME = "MyCppProject" —— 设置项目名称
- OUTPUT_DIRECTORY = docs —— 指定输出目录
- INPUT = src include —— 指定源码和头文件路径
- RECURSIVE = YES —— 是否递归扫描子目录
- EXTRACT_ALL = YES —— 提取所有函数，即使没有注释
- GENERATE_HTML = YES —— 生成HTML文档
- GENERATE_LATEX = NO —— 不需要可设为NO
- ENABLE_PREPROCESSING = YES —— 支持宏和条件编译解析
编写符合Doxygen格式的注释
Doxygen能识别多种注释风格，推荐使用Qt风格或JavaDoc风格。以下是一个标准的函数注释示例：
/*** 计算两个整数的和
* @param a 第一个加数
* @param b 第二个加数
* @return 返回两数之和
* @see subtract()
*/
int add(int a, int b);
类的注释可以这样写：
/*** 表示一个二维点的类
* 可用于图形计算或坐标系统处理
*/
class Point {
public:
Point(double x, double y);
double getX() const;
double getY() const;
private:
double m_x, m_y;
};
支持使用\brief、\details、\note等命令增强文档语义。
生成并查看文档
配置完成后，在终端执行：
doxygen Doxyfile
Doxygen会解析源码并生成文档。如果配置了HTML输出，可在docs/html/index.html中打开主页面。浏览器中即可查看完整的类图、函数索引、调用关系等。
若启用了CLASS_DIAGRAMS和HAVE_DOT（需安装Graphviz），还能自动生成UML类图和函数调用图。
集成到构建流程
建议将文档生成加入CI/CD流程或Makefile中。例如在Makefile中添加：
doc:doxygen Doxyfile
开发者只需运行make doc即可更新文档。也可以配置GitHub Actions在每次推送时自动部署HTML文档到Pages。
基本上就这些。只要保持注释规范，Doxygen就能帮你持续维护高质量的API文档。不复杂但容易忽略的是注释的及时更新——代码变，注释也得跟上。
