使用 Doxygen GUI 为 C++ 项目生成文档

✨ 使用 Doxygen GUI 为 C++ 项目生成文档

在 C++ 项目中维护良好的代码文档是一种习惯，也是一种能力。本文将通过 GUI 图形界面方式，介绍如何使用 Doxygen 工具生成结构清晰、支持类图和函数调用图的 HTML 文档。

---

🧰 准备工作

1. 安装 Doxygen

访问官网下载并安装：https://www.doxygen.nl/download.html

安装后会包含两个工具：

• Doxygen GUI frontend（图形界面）
• doxygen 命令行工具

本文使用图形界面操作。

2. 安装 Graphviz（可选但强烈推荐）

Doxygen 支持生成类图、调用图、include 依赖图，但这依赖于 Graphviz 提供的 dot 工具。

安装完成后请将 Graphviz/bin 添加到系统环境变量 PATH。

3. 设置产出文档语言（可选）

如果希望 Doxygen 生成中文界面文档，可以在 GUI 中切换至 Expert 选项卡，搜索 OUTPUT_LANGUAGE，并设置为 Chinese：

OUTPUT_LANGUAGE = Chinese

这么生成的 HTML 页面会是中文界面，包括类列表、成员函数说明、查看页等，更适合国内队伍和外部合作。

---

📦 示例项目结构

我们以一个名为 AoiSharedMemoryLib 的项目为例，结构如下：

AoiSharedMemoryLib/
├── src/
│   ├── IProcessor.h
│   ├── CProcessorBase.h
│   └── ShareAoiMap.h
├── docs/
└── Doxygen 输出将生成于此

项目中的核心接口和实现类已使用 Doxygen 风格注释 书写，例如：

/**
 * @brief 等待信号
 * @return 操作结果
 */
virtual GReturn WaitSignal() = 0;

---

🚀 使用 Doxygen GUI 输出 HTML 文档

第一步：配置基本信息

打开 Doxygen GUI frontend，填写：

项目项	示例
Working directory	AoiSharedMemoryLib/ 项目根目录
Project name	AoiSharedMemoryLib
Project synopsis	一个轻量级的共享内存通信库
Project version	v1.0.0
Source code dir	src/
Destination dir	docs/
✅ Scan recursively	勾选，确保递归扫描子文件夹

📌 可选：设置项目 logo（推荐 PNG）用于页面页眉展示。

🔹 工作目录

• 填写你的工程根目录，也可以点击 Select... 按钮手动选择。

🔹 Project 信息（右侧）

项目	操作说明
Project name	项目名称
Project synopsis	项目描述
Project version or id	版本号
Project logo	logo 图

🔹 Source code directory

• 点击右侧 Select...，选择你包含 .h、.cpp 的目录（建议是整个 src/、include/ 等根目录）
• ✔ 勾选 Scan recursively（表示递归扫描子文件夹）

🔹 Destination directory

• 点击 Select...，选择你希望生成的文档存放的位置（例如 docs/）

然后点击右下角的 Next。

✅ 项目信息配置（Project）

配置项	当前设置	优化建议说明
项目名称	AoiSharedMemoryLib	✅ 合理，名称清晰、具备标识性
项目简介	AoiSharedMemoryLib 是一个轻量级的共享内存通信库	✅ 建议略作扩展说明用途：例如 “面向 AOI 与控制器之间的高效命令与图像传输”
项目版本	v1.0.0	✅ 使用语义化版本号有助于文档识别和迭代记录
项目 Logo	✔ 已选择自定义极简风格 PNG 图标	✅ 视觉上提升文档整体专业度，推荐保留

✅ 路径配置（源码与输出）

配置项	当前路径设置	优化建议说明
源码路径	AoiSharedMemoryLib/src	✅ 合理，建议保证此目录下包含 .h / .cpp 等源码文件
递归扫描源码目录	✔ 已启用	✅ 推荐开启，确保子目录（如 include/、impl/）也被分析
输出文档路径	AoiSharedMemoryLib/docs	✅ 清晰明了，建议将 HTML 输出集中于此便于管理（如 docs/html/）

第二步：模式设置（Mode）

• ✔ All Entities（提取所有代码）
• ✔ Include cross-referenced source code
• ✔ Optimize for C++ output

1️⃣ Extraction Mode（提取模式）

选项	建议	说明
Documented entities only	❌	只提取带注释的元素，可能会漏掉有用代码
All Entities	✅	推荐，提取所有类/函数，无论是否注释，适合文档完整性需求
Include cross-referenced source code in the output	✅	如果你希望文档中可以点击跳转源码（推荐勾选）

2️⃣ Programming Language Optimization（语言优化）

选项	建议	说明
Optimize for C++ output	✅	必须选这个！ 你的项目是标准 C++
其他语言选项	❌	与你的项目无关

第三步：输出格式（Output）

• ✔ HTML

  • ✔ with navigation panel
  • ✔ with search function

• ❌ LaTeX（如不需要 PDF 可不勾选）

🔍 当前配置评估

设置项	当前状态	是否合理
✅ HTML	✔ 勾选	✅
◉ with navigation panel	✔ 勾选	✅
☑ With search function	✔ 勾选	✅
❌ LaTeX/PDF 等其它格式	未勾选	✅
❌ CHM、RTF、XML、Man Pages 等	未勾选	✅

📝 导出 PDF 文档

安装 LaTeX 工具链（例如 TeX Live）来将生成的 .tex 文件转换成 PDF。

步骤如下（命令行操作）：

cd latex/
make

然后会生成 refman.pdf，这就是 PDF 版文档。

✅ 建议：

你是否需要 PDF 文档？	推荐操作
❌ 不需要	只勾选 HTML，取消 LaTeX
✅ 需要（比如写报告）	保留 LaTeX，稍后手动编译

第四步：图示配置（Diagrams）

• ✔ Use dot tool from the GraphViz package

• ✔ 勾选所有图示类型：

  • Class graphs
  • Call graphs
  • Include dependency graphs
  • Collaboration diagrams 等

需要 Graphviz 已正确安装并配置环境变量

🔧 当前设置确认：

设置项	状态	说明
Use dot tool from GraphViz	✅ ✔	启用了 Graphviz 支持
Class graphs	✅ ✔	类继承关系图
Collaboration diagrams	✅ ✔	类之间交互图
Overall class hierarchy	✅ ✔	整体类层次结构图
Include dependency graphs	✅ ✔	头文件 include 关系图
Included by dependency graphs	✅ ✔	被谁 include 的图
Call graphs	✅ ✔	函数调用图
Called by graphs	✅ ✔	函数被调用图

---

✅ 最后一步：运行生成

切换到顶部的 Run 标签页，点击：

[ Run doxygen ]

生成完成后点击：

[ Show HTML output ]

即可在浏览器中查看完整的 API 文档。

---

🔐 补充配置：禁止显示 .cpp 中的代码

如果你不希望对外文档显示 .cpp 文件中的代码或实现细节，可以在 GUI 中手动设置或直接在 Doxyfile 中配置如下项：

SOURCE_BROWSER        = NO
INLINE_SOURCES        = NO
STRIP_CODE_COMMENTS   = YES

解释：

• SOURCE_BROWSER = NO 禁止生成源码浏览页（不再有 .cpp 页面）
• INLINE_SOURCES = NO 禁止在函数文档中显示实现代码
• STRIP_CODE_COMMENTS = YES 移除源码中非 Doxygen 注释（无效于普通注释的 .cpp 代码）

当您确认 .cpp 文件 未使用 Doxygen 注释风格 时，这三项设置合计使 Doxygen 不再显示任何 .cpp 代码内容，也不会将其给加入函数列表中。

如需更加严格，可以配合

FILE_PATTERNS = *.h *.hpp

或

INPUT = include/

仅扫描头文件，完全排除 .cpp 文件影响。

---

📂 生成结果结构

文档将输出到：

docs/html/index.html

包含：

• 项目主页
• 类结构图、调用图
• 所有函数与成员变量文档
• 交叉链接源码浏览功能

---

✏️ Git 提交建议

git commit -m "docs: 添加 Doxygen 注释与文档生成配置"

可以将生成的文档目录加入 .gitignore，保留 src/ 注释即可。

---

📌 总结

• Doxygen GUI 是 C++ 项目中文档构建的高效入口
• 配合 @brief, @param, @return, @struct, @file 等注释标签，可构建完善的开发者文档
• 推荐将 docs/ 提交至 Git 仓库或托管至 GitHub Pages