文档化接口：用Doxygen写出让人想读的接口文档
说实话，我见过太多优秀的C语言接口，最后死在文档上。
代码写得再漂亮，如果没人看得懂怎么用，那跟没写有什么区别？我个人习惯在写接口的第一天就把Doxygen注释跟上。这不是什么额外负担，而是对自己未来的一种投资——你想想看，三个月后你自己回来看这段代码，没有注释的话，你真的还记得每个参数是干嘛的吗？
为什么非得是Doxygen？
市面上文档生成工具不少，但Doxygen在C语言生态里，基本就是事实标准。我曾在项目里试过用Sphinx配合Breathe，最后还是回到Doxygen——原因很简单：它原生理解C语言的语法结构，不需要你额外写一堆配置文件。
说白了，Doxygen能帮你做三件事：
- 从注释自动生成文档——你写一次注释，它帮你生成HTML、PDF、甚至手册页
- 保持代码与文档同步——改代码时顺手改注释，文档自动更新
- 生成调用图和依赖图——这对理解模块间关系特别有用
核心原则：Doxygen注释不是写给机器看的，是写给下一个维护者（包括未来的你）看的。注释的质量决定了接口的可维护性。
Doxygen注释的基本格式
Doxygen支持两种注释风格，我个人偏爱Javadoc风格，因为它更清晰：
/**
* @brief 初始化定时器模块
* @param timer_id 定时器ID，范围0-3
* @param period_ms 定时周期，单位毫秒
* @return 0表示成功，-1表示参数无效
*
* 调用此函数前需要先调用 timer_power_up() 使能电源。
* 定时器启动后，会以固定周期触发回调。
*/
int timer_init(uint8_t timer_id, uint32_t period_ms);嗯，这里要注意：@brief 是必须的，它会在文档的概要部分显示。而详细描述放在后面，可以写多行。
接口文档必须包含的要素
我在项目中踩过最大的坑，就是接口文档只写了「这个函数做什么」，但没写「什么情况下不能调用它」。避坑指南：我曾经因为没写清楚前置条件，导致同事在中断上下文里调用了带锁的函数，直接死锁。
一个完整的接口文档，至少应该包含以下内容：
| 要素 | Doxygen标签 | 说明 |
|---|---|---|
| 功能简述 | @brief | 一句话说清楚这个接口是干嘛的 |
| 参数说明 | @param | 每个参数的含义、取值范围 |
| 返回值 | @return | 所有可能的返回值及其含义 |
| 前置条件 | @pre | 调用前必须满足的条件 |
| 后置条件 | @post | 调用后系统状态的变化 |
| 注意事项 | @note | 线程安全、可重入性、中断上下文限制等 |
| 示例代码 | @code | 一段可编译的调用示例 |
我的习惯：每个公开接口都写 @pre 和 @post。这两个标签能逼你思考接口的契约，而不是只描述行为。
模块级文档：让使用者快速上手
除了函数级别的注释，模块级别的文档更重要。你想想看，一个新同事接手你的代码，他首先想知道的是「这个模块是干嘛的」「怎么用」「有哪些坑」。
Doxygen支持在文件头部写模块文档：
/**
* @file timer.h
* @brief 定时器管理模块
*
* 本模块提供硬件定时器的统一管理接口。
* 支持4个独立定时器通道，每个通道可配置不同周期。
*
* 使用流程：
* 1. 调用 timer_power_up() 使能定时器外设时钟
* 2. 调用 timer_init() 初始化具体通道
* 3. 调用 timer_start() 启动定时
* 4. 在回调函数中处理定时事件
* 5. 调用 timer_stop() 停止定时
*
* @note 本模块不可重入，所有接口禁止在中断中调用
* @warning 定时器回调中不要执行耗时操作，建议只发信号量
*/
这样生成的文档里，会有一个独立的模块页面，把所有接口按逻辑分组展示。比散落在各个函数页面里好找得多。
分组与模块化：用@defgroup组织接口
当模块接口比较多时，我建议用 @defgroup 和 @{ @} 来分组。这就像给接口打标签，生成文档时会自动归类：
/**
* @defgroup Timer_Init 定时器初始化接口
* @{
*/
int timer_init(uint8_t timer_id, uint32_t period_ms);
void timer_deinit(uint8_t timer_id);
/** @} */
/**
* @defgroup Timer_Control 定时器控制接口
* @{
*/
int timer_start(uint8_t timer_id);
int timer_stop(uint8_t timer_id);
int timer_reset(uint8_t timer_id);
/** @} */
生成的文档里，初始化接口和控制接口会分在两个不同的章节，清晰得很。
SVG：Doxygen文档生成的核心流程
下面这张图展示了从注释到最终文档的完整流程，我建议你把它贴在团队文档规范里：
实战：一个完整的接口文档示例
光说不练假把式。下面是我在一个物联网项目里实际用过的接口文档模板，你直接拿去改改就能用：
/**
* @brief 发送数据到指定设备
* @param dev_addr 目标设备地址（MAC格式，6字节）
* @param data 待发送数据缓冲区指针
* @param len 数据长度，单位字节，最大1024
* @param timeout_ms 等待超时时间，单位毫秒，0表示不等待
* @return 发送结果
* @retval 0 发送成功
* @retval -EINVAL 参数无效（dev_addr为NULL或len超出范围）
* @retval -ETIMEDOUT 发送超时
* @retval -EIO 硬件错误
*
* @pre 调用前需确保设备已通过 dev_connect() 建立连接
* @post 发送成功后，数据被放入发送队列，但不保证对方已收到
*
* @note 本函数是线程安全的，内部使用互斥锁保护
* @warning 不要在中断服务函数中调用此函数，可能导致调度延迟
*
* @code
* uint8_t addr[6] = {0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF};
* uint8_t buf[] = "Hello, Device!";
* int ret = dev_send(addr, buf, sizeof(buf), 1000);
* if (ret == 0) {
* printf("发送成功\n");
* }
* @endcode
*/
int dev_send(const uint8_t *dev_addr, const uint8_t *data,
size_t len, uint32_t timeout_ms);注意：很多人写 @retval 只写成功的情况，忽略了错误码。我曾经在一个项目中，接口返回了5种错误码，文档里只写了3种。结果同事花了两天时间排查一个「未定义错误码」的问题——其实就是文档没写全。
配置Doxygen生成漂亮的文档
Doxygen的默认配置生成的文档……嗯，说实话有点丑。我建议你至少改这几个选项：
# 开启优化输出
OPTIMIZE_OUTPUT_FOR_C = YES
# 提取所有注释，包括静态函数
EXTRACT_ALL = YES
EXTRACT_STATIC = YES
# 生成调用图
CALL_GRAPH = YES
CALLER_GRAPH = YES
# 使用点阵图生成更清晰的图表
DOT_IMAGE_FORMAT = svg
INTERACTIVE_SVG = YES
# 按模块分组显示
GROUP_GRAPHS = YES
# 输出HTML时使用搜索功能
SEARCHENGINE = YES
我个人习惯把 Doxyfile 也纳入版本管理。这样团队所有人都用同一套配置，生成的文档风格统一。
文档审查：比代码审查更重要
你可能觉得文档审查是浪费时间。但我告诉你，文档审查发现的问题，往往比代码审查更致命——因为文档错了，别人会按照错误的方式调用你的接口。
我建议在代码审查的 checklist 里加上这几条：
- 每个公开接口都有 @brief、@param、@return 吗？
- 前置条件和后置条件写清楚了吗？
- 有没有说明线程安全和中断上下文限制？
- 示例代码能编译通过吗？
- 模块级别的使用流程写了吗？
一个小技巧：在CI流水线里加上 doxygen 命令，如果生成过程中有警告（比如某个参数没写注释），就让流水线失败。这样能强制团队养成写注释的习惯。
好了，关于Doxygen文档化接口，核心就是这些。记住一句话：好的接口文档，不是写完了就完事，而是要让下一个开发者拿到文档后，不需要看代码就能正确使用你的接口。这才是真正的模块解耦。
公众号:蓝海资料掘金营，微信deep3321