Ubuntu C++文档如何生成

在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和参数，写代码时直接生成文档，效率提升不少。