Doxygen 是一款功能强大、开源且跨平台的自动化文档生成工具。它的核心作用是从源代码中提取特定格式的注释，自动生成结构化、可导航且高质量的技术文档。

Doxygen 最初由荷兰工程师 Dimitri van Heesch 于 1997 年创建，旨在解决大型 C++ 项目的文档化难题。如今，它已成为软件开发中“代码即文档（Documentation as Code）”理念的关键实践工具，能够有效解决“代码更新快、文档跟不上”的行业痛点。

介绍

 Doxygen 的核心亮点

• 广泛的编程语言支持：完美支持 C、C++、Java、Objective-C、Python、C#、PHP、IDL、Fortran、VHDL 等多种编程语言，尤其对 C++ 的复杂语法（如模板、宏等）有着业界标杆级的解析能力。
• 多格式文档输出：可以一键生成多种格式的文档以满足不同场景需求。默认生成带有搜索和导航栏的 HTML 网页（适合团队在线查阅）；也支持生成 LaTeX/PDF（适合交付正式手册）、RTF（兼容 Word）、CHM（Windows 帮助文件）以及 XML（供其他工具二次加工）等。
• 强大的可视化图表：如果配合安装 Graphviz 工具，Doxygen 能自动根据代码逻辑生成直观的图表，例如类继承图、函数调用关系图、文件依赖图和模块协作图等，帮助开发者快速理解复杂的代码架构。
• 灵活的注释语法：支持多种注释风格，包括 Javadoc 风格（/** ... */）、Qt 风格（/*! ... */）以及简单的 C++ 风格（///），并且原生支持在注释中编写 Markdown 语法，极大提升了文档编写的体验。

如何使用 Doxygen？

使用 Doxygen 的流程非常标准化，通常只需简单的四步：

1. 安装工具：在 Windows、macOS 或 Linux 系统上下载并安装 Doxygen（如果需要生成图表，建议同时安装 Graphviz）。
2. 生成配置文件：在项目根目录下运行命令 doxygen -g，它会自动生成一个名为 Doxyfile 的默认配置文件。
3. 按规范写注释：在编写代码时，按照 Doxygen 的语法规则（如使用 @brief、@param、@return 等标签）为文件、类、函数等添加注释。
4. 生成文档：直接在命令行运行 doxygen（或 doxygen Doxyfile），工具就会根据配置文件读取源码，并在指定的输出目录（默认为 ./html）中生成完整的文档。

示例

/**
 * @brief 计算两个整数的和
 * 
 * 这是一个简单的加法函数，用于演示 Doxygen 的注释格式。
 * 
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两个参数相加后的结果
 */
int add(int a, int b) {
    return a + b;
}

Doxygen 集成到 VS Code 中

主要分为两个核心环节：

一是安装系统级的 Doxygen 工具（负责最终生成文档）

二是安装VS Code 插件（负责辅助你快速编写规范的注释）

1. 安装系统级 Doxygen 工具

VS Code 的插件只是辅助工具，真正生成文档依赖于本地安装的 Doxygen。如果你的电脑里没有它，插件在生成文档时会报错（如提示 command not found）。

• Windows：去 Doxygen 官网下载安装包（如 doxygen-x.x.x-setup.exe），安装时务必勾选 “Add doxygen to PATH”（添加到系统环境变量），安装完成后重启 VS Code。
• macOS：在终端执行命令 brew install doxygen。
• Linux (Ubuntu/Debian)：在终端执行命令 sudo apt install doxygen。

验证安装：打开 VS Code 的内置终端，输入 doxygen -v，如果能正常输出版本号，说明安装成功。

2. 安装 VS Code 辅助插件

为了不用手敲繁琐的 /** @brief ... */ 格式，推荐安装代码注释生成插件。

• 打开 VS Code 左侧的扩展商店（Extensions），搜索并安装 “Doxygen Documentation Generator”（作者：cschlosser，这是目前最主流的插件）。
• 使用方法：安装后，将光标放在函数、类或变量的上一行，按下快捷键 Ctrl+Alt+D（macOS 为 Cmd+Alt+D），插件就会自动识别代码结构并生成包含 @param、@return 等标签的注释模板。

3. 生成并配置 Doxyfile 文件

Doxyfile 是 Doxygen 的核心配置文件，决定了扫描哪些代码、输出什么格式的文档。

1. 在 VS Code 中打开你的项目根目录。
2. 打开终端，执行命令 doxygen -g。这会在当前目录下生成一个默认的 Doxyfile 文件。
3. 用 VS Code 打开 Doxyfile，修改以下几个关键配置项（可以直接搜索对应参数名进行修改）：

表格

参数名	推荐设置	说明
PROJECT_NAME	"MyProject"	你的项目名称，会显示在文档首页
INPUT	./src ./include	指定需要扫描的源码目录（用空格隔开）
RECURSIVE	YES	是否递归扫描子目录
OUTPUT_DIRECTORY	./docs	指定生成的文档存放目录
GENERATE_HTML	YES	是否生成网页版文档

4. 生成并查看文档

配置好 Doxyfile 并在代码中写好了 Doxygen 格式的注释后，就可以生成文档了：

1. 在 VS Code 终端中，确保当前路径在项目根目录下，执行命令：doxygen（或 doxygen Doxyfile）。
2. 如果配置无误，终端会输出扫描进度。生成完毕后，去你设置的输出目录（如 docs/html）下，找到并双击打开 index.html，即可在浏览器中看到漂亮的代码文档。

• 自定义注释样式：如果你不喜欢插件默认的 /** ... */ 格式，可以在 VS Code 的设置（settings.json）中配置 doxdocgen 相关参数。例如将注释前缀改为 ///，或自定义 @param 的模板格式。
• 高亮 Doxygen 注释：为了让文档注释在代码中更显眼，可以在 settings.json 中添加 editor.tokenColorCustomizations 配置，单独为 Doxygen 的注释块和标签（如 @brief）设置特定的颜色和加粗样式。