29、文档与注释：Doxygen跨平台文档生成、代码注释规范

说实话，很多C语言开发者对文档的态度是「能跑就行」。

我见过太多项目，代码写得漂亮，但半年后连原作者自己都看不懂了。你想想看，跨平台开发本身就够复杂了，要是连注释都没有规范，那简直就是给自己挖坑。

今天我们就聊聊Doxygen这套工具，以及我这些年总结出来的注释规范。

为什么非得用Doxygen？

你可能用过一些自动文档生成工具。但Doxygen不一样，它原生支持C语言，而且跨平台能力极强——Windows、Linux、macOS都能跑。

我个人习惯是：只要写公共接口，就必须配Doxygen注释。为什么？因为跨平台项目往往需要多人协作，不同平台上的开发者可能用不同的IDE。Doxygen生成的HTML文档，谁都能看，谁都能理解。

Doxygen注释的基本格式

Doxygen支持多种注释风格。我推荐用/** ... */这种，因为它一眼就能和普通注释区分开。

/**
 * @brief 初始化网络连接
 * @param host 服务器地址，支持IPv4和IPv6
 * @param port 端口号，范围1-65535
 * @return 成功返回0，失败返回-1
 * @note 调用前需要先调用 net_init()
 */
int net_connect(const char* host, int port);

嗯，这里要注意：@brief是必须的。它会在文档摘要中显示，方便快速浏览。

我常用的Doxygen标签

这些年我用下来，真正高频的标签其实就这几个：

标签	用途	我的建议
@brief	简短描述	必须写，一句话说清楚功能
@param	参数说明	每个参数都要写，包括NULL的情况
@return	返回值说明	明确写出成功/失败的条件
@note	注意事项	调用前提、线程安全等
@see	相关函数	方便跳转阅读
@deprecated	标记废弃	写明替代方案

跨平台项目中的注释规范

跨平台开发有个痛点：不同平台上的行为可能不一样。比如文件路径分隔符，Windows用反斜杠，Linux用正斜杠。

我曾经在一个项目中吃过这个亏。一个同事在Windows上写的注释说「路径用\\分隔」，结果Linux上的开发者直接复制代码，编译报错。后来我定了一条规矩：注释中涉及平台差异的地方，必须显式标注。

/**
 * @brief 打开配置文件
 * @param path 配置文件路径
 *             注意：Windows下使用 UTF-16 编码
 *             Linux/macOS 下使用 UTF-8 编码
 * @return 文件句柄，失败返回 NULL
 * @note 调用者需要调用 config_close() 释放资源
 */
FILE* config_open(const char* path);

文件头注释：项目的「身份证」

每个源文件和头文件，我都要求加上文件头注释。这不是形式主义，而是为了快速定位问题。

/**
 * @file    network.c
 * @brief   网络层跨平台实现
 * @author  张三 <zhangsan@example.com>
 * @date    2024-01-15
 * @version 2.1.0
 *
 * 支持平台：
 * - Windows (WinSock2)
 * - Linux   (POSIX socket)
 * - macOS   (BSD socket)
 *
 * @note 本文件使用条件编译处理平台差异
 */

我个人习惯在文件头里写上「支持平台」列表。这样后来者接手时，能快速知道这个文件在哪些平台上验证过。

避坑指南：我曾经踩过的坑

我曾经在一个大型嵌入式项目中，因为注释不规范，导致整个团队浪费了两周时间排查一个bug。

事情是这样的：一个函数timer_start()，注释里只写了「启动定时器」，但没说明定时器是单次触发还是周期触发。结果A平台的实现是单次，B平台的实现是周期。两个平台的代码都「正确」，但行为完全不一样。

从那以后，我要求所有涉及「行为语义」的函数，必须在注释里明确写出：

• 这个函数是同步还是异步？
• 有没有副作用？
• 线程安全吗？
• 内存谁负责释放？

Doxygen的配置与生成

Doxygen的配置其实很简单。我一般用doxygen -g生成默认配置，然后改几个关键项：

# 项目名称
PROJECT_NAME           = "MyCrossPlatformLib"
# 输出语言
OUTPUT_LANGUAGE        = Chinese
# 提取所有注释
EXTRACT_ALL            = YES
# 包含源代码
SOURCE_BROWSER         = YES
# 生成调用关系图
CALL_GRAPH             = YES

运行doxygen Doxyfile，就能生成HTML文档了。我个人习惯把文档输出到docs/目录，然后提交到Git仓库。这样团队成员随时都能查看。

知识体系结构图

下面这张图是我对文档与注释体系的理解，你可以对照着看看自己有没有遗漏：

一些实用建议

最后，分享几个我这些年总结出来的实用建议：

• 注释要「说人话」。别写「该函数用于执行初始化操作」，直接写「初始化网络连接」就行。
• 代码和注释要同步更新。我见过最坑的就是注释和代码对不上。改代码的时候顺手改注释，养成习惯。
• 不要过度注释。比如i++这种代码，你写个「i自增1」就是废话。注释应该解释「为什么这么做」，而不是「做了什么」。
• 用Doxygen生成文档后，定期检查。看看有没有遗漏的函数，有没有格式错误。

---

公众号:蓝海资料掘金营，微信deep3321