3、Doxygen入门：Doxygen是什么？它能做什么？安装与基本配置（Doxyfile）

好，咱们进入第三个章节。前面两章我们聊了为什么要写文档，以及文档的几种风格。这一章，我们来点实在的——上手一个工具。

说到嵌入式C的文档生成工具，Doxygen绝对是绕不开的。我当年刚入行时，带我的老工程师丢给我一句：「代码写完了？把Doxygen注释补上。」那时候我还一脸懵，心想这玩意儿是啥？后来用顺手了，才发现——真香。

3.1 Doxygen是什么？

Doxygen，说白了就是一个源代码文档自动生成工具。你只需要在代码里按照特定格式写注释，它就能帮你把这些注释提取出来，生成一份漂亮的文档。

它支持多种输出格式：HTML、PDF、LaTeX、RTF、Man Page……我个人最常用的是HTML，因为方便在浏览器里直接看，团队里谁都能打开。

它支持的语言也很多：C、C++、Java、Python、PHP、C#……当然，咱们嵌入式C工程师最关心的就是C和C++。

3.2 它能做什么？

我简单列一下它的核心能力，你感受一下：

• 提取函数、变量、宏、结构体的注释，自动生成API文档
• 生成调用关系图——谁调了谁，一目了然。我在调试一个3000行的驱动时，全靠这个图理清脉络
• 生成继承图、协作图——对于面向对象风格的C代码（比如用结构体+函数指针模拟类），特别有用
• 支持分组、模块化——你可以把相关函数归到一个「模块」里，文档结构更清晰
• 支持包含代码示例——直接在注释里嵌入示例代码，文档里会原样展示
• 支持数学公式——如果你写算法库，可以用LaTeX公式

嗯，这里要注意一点：Doxygen不是帮你写注释的，它只是帮你整理和呈现注释。注释还得你自己写。

3.3 安装Doxygen

安装其实很简单。我以最常见的几种环境为例：

Windows

去官网下载安装包，一路Next就行。我个人建议勾选「添加到PATH」，这样可以在命令行里直接调用。

Linux（Ubuntu/Debian）

sudo apt-get install doxygen

macOS

brew install doxygen

装完之后，在终端输入 doxygen --version，如果能看到版本号，就说明装好了。

3.4 基本配置：Doxyfile

Doxygen的配置是通过一个叫 Doxyfile 的文件来控制的。这个文件有几百个选项，但你不用全记住。我教你一个快速上手的方法。

3.4.1 生成默认配置

在项目根目录下执行：

doxygen -g

这会生成一个默认的 Doxyfile。打开它，你会发现里面全是注释和配置项。别慌，我们只改几个关键的。

3.4.2 必须改的几个配置

配置项	说明	我的推荐值
PROJECT_NAME	项目名称，会显示在文档标题上	你的项目名，比如 "MyEmbeddedProject"
PROJECT_BRIEF	项目简介，一句话描述	"嵌入式传感器驱动库"
INPUT	指定源代码目录	默认是当前目录 .，也可以改成 ./src
OUTPUT_DIRECTORY	文档输出目录	./docs
RECURSIVE	是否递归搜索子目录	YES —— 我建议打开，省事
EXTRACT_ALL	是否提取所有实体（即使没有注释）	YES —— 新手阶段建议打开，能看到所有函数
GENERATE_HTML	是否生成HTML文档	YES
HAVE_DOT	是否使用Graphviz画图	YES —— 如果你装了Graphviz
CALL_GRAPH	是否生成调用关系图	YES

我曾经犯过一个错：忘了把 RECURSIVE 设成 YES，结果只生成了根目录下的文件，子目录里的驱动代码全没被扫描到。排查了半天才发现是这个问题。嗯，你记得避坑。

3.4.3 快速修改的方法

你当然可以用文本编辑器打开Doxyfile手动改。但我更推荐用命令行方式：

doxygen -g
# 然后直接修改几个关键项
sed -i 's/PROJECT_NAME           = "My Project"/PROJECT_NAME           = "SensorDriverLib"/' Doxyfile
sed -i 's/EXTRACT_ALL            = NO/EXTRACT_ALL            = YES/' Doxyfile
sed -i 's/RECURSIVE              = NO/RECURSIVE              = YES/' Doxyfile

这样改起来快，而且不容易手滑改错格式。

3.5 生成文档

配置好Doxyfile之后，生成文档就一行命令：

doxygen Doxyfile

然后你会在 OUTPUT_DIRECTORY 指定的目录下看到生成的HTML文件。用浏览器打开 index.html，就能看到你的文档了。

3.6 我的个人工作流

最后分享一下我现在是怎么用Doxygen的：

1. 项目初始化时，执行 doxygen -g 生成Doxyfile
2. 修改几个关键配置（项目名、输入路径、递归、图表）
3. 把Doxyfile提交到Git仓库——这样团队里所有人都用同一套配置
4. 每次提交代码前，跑一遍 doxygen，看看文档有没有异常
5. 持续集成（CI）里也加一步，自动生成文档并部署到内部Wiki

你想想看，如果每次代码变更，文档都能自动更新，那该多省心。我见过太多项目，代码改了三版，文档还停留在第一版。用Doxygen，至少能保证文档和代码是同步的——前提是你写了注释。

好，这一章就到这里。下一章我们聊聊Doxygen注释到底怎么写，有哪些坑要避开。到时候我会拿一段真实的嵌入式驱动代码来演示，你准备好了吗？