在Ubuntu环境下为C++项目生成文档，Doxygen几乎是绕不开的标准工具。配合Graphviz还能输出类图、调用图这些可视化内容，效果很直观。下面就把从安装到生成HTML、PDF的完整流程说明白，顺带聊聊注释规范和VS Code的集成要点。
一 安装与准备
先搞定工具本身。Doxygen是主角，图形向导能帮我们可视化管理配置，但不是必须的。安装命令很直接：
- 安装Doxygen及图形向导：
sudo apt-get install doxygen doxygen-gui - 安装Graphviz，用来生成类图和调用图：
sudo apt-get install graphviz - 验证一下版本：
doxygen --version，通常输出类似1.9.1
如果要在HTML中显示关系图，得确保Graphviz正常运行。Doxygen配置里有个DOT_PATH选项，指向dot可执行文件的位置就行，一般装好会自动识别。
二 快速上手步骤
项目根目录下执行doxygen -g，会生成一个叫Doxyfile的默认配置文件。接下来按需编辑它，比如设置输入输出目录、开启递归扫描、启用Graphviz图形等。几种常用配置项在下一节会详细说。
配置完成后，运行doxygen Doxyfile，文档就生成好了。打开html/index.html就能看到API文档的全貌。
三 关键配置与输出格式
Doxyfile里需要关注哪些配置项？这里列几个关键点：
- 项目信息：
PROJECT_NAME和PROJECT_NUMBER，名字和版本号总得写清楚。 - 输出控制：
OUTPUT_DIRECTORY指定输出目录，GENERATE_HTML和GENERATE_LATEX决定生成HTML还是PDF。 - 源码与示例：
FILE_PATTERNS设置扫描的文件类型（比如*.h *.cpp），RECURSIVE开启递归扫描，EXAMPLE_PATH指定示例代码路径。 - 关系图：
HA VE_DOT = YES是前提，CALL_GRAPH和CALLER_GRAPH设为YES就能生成调用图和被调用图。 - 源码浏览：
SOURCE_BROWSER = YES让HTML里可以直接查看源码，GENERATE_TREEVIEW = ALL生成树形导航。
输出格式的链路也很清晰：
- HTML：直接打开
html/index.html。 - PDF：启用
GENERATE_LATEX = YES后，进入latex目录执行make，PDF就生成了。
四 注释规范与示例
文档写得好不好，关键看注释规不规范。Doxygen支持多种风格，下面给出两个典型示例。
文件头注释
/**
* @brief 简要说明
* @file 文件名
* @author 作者
* @version 版本
* @date 日期
* @note 备注
* @since 起始版本
*/函数注释
/**
* 函数概述
* @param[in] a 输入参数说明
* @param[in] s 输入参数说明
* @param[out] 返回值说明
* @return 返回值解释
* @warning 注意事项
* @note 注解
* @see 关联函数或类
*/常用的命令有@brief、@param、@return、@note、@warning、@see等，兼容Qt-Doc、KDoc、Ja vaDoc多种风格，上手很快。
五 在VS Code中集成
开发环境上，VS Code和Doxygen的配合也很重要。安装C/C++和Doxygen扩展后，语法高亮和注释提示都很方便。如果觉得手动编辑Doxyfile麻烦，可以用doxygen-gui做可视化配置，省时省力。
更进一步，可以在VS Code的tasks.json里配置一键运行Doxygen的命令，比如配上doxygen和参数，写代码时直接生成文档，效率提升不少。
