如何用Doxygen/Clang等工具强制C++函数文档声明所有返回码？

• 我们的C++代码库用枚举类RC作为统一返回码，定义类似enum class RC: UINT32 { kSuccess, kNoMem, kIoError...}
• 现有编码规范通过Doxygen和Clang约束：函数文档必须用@param标注所有参数，用@return说明返回值，但仅校验@return的存在性
• 需要实现强制函数文档声明所有可能返回的RC值（包括函数直接返回、调用其他函数间接返回的情况），解决手动维护易遗漏的问题（比如被调用函数新增返回码后，调用方文档没同步更新）
• 试过配置Clang-Tidy、Doxygen，没找到现成方案

1. 自定义Clang-Tidy检查器 #

这是最靠谱的落地方式，Clang-Tidy支持扩展自定义规则，核心逻辑如下：

• 遍历函数的所有返回路径，收集直接返回的RC枚举值
• 分析函数内部调用的其他返回RC的函数，递归提取这些函数文档里声明的返回码
• 对比当前函数文档中（可以用@return下的列表，或自定义@rc标签）的返回码集合，只要有未声明的就触发警告
• 优势：能自动关联被调用函数的返回码变更，不用手动同步；可以集成到CI流水线里强制校验
• 实现关键点：
  • 基于Clang AST遍历函数体，识别return语句里的RC枚举实例
  • 解析被调用函数的Doxygen文档，提取已声明的返回码列表
  • 加自定义配置项，允许忽略内部未导出函数等特殊场景

2. Doxygen后处理脚本扩展 #

利用Doxygen的XML输出能力，写脚本做校验：

• 配置Doxygen生成XML格式的文档输出，里面包含函数的返回码声明、函数调用关系
• 用Python或其他脚本解析XML：
  1. 为每个函数生成完整的返回码集合（直接返回值 + 所有调用函数的返回码）
  2. 和文档里声明的返回码列表对比，生成差异报告
• 优势：复用现有Doxygen配置，不用改编译流程；适合作为文档质量检查的一环
• 注意：得自定义Doxygen标签（比如@rc）来明确标记每个返回码的说明，方便脚本提取

3. 代码生成工具辅助维护 #

如果项目有统一的代码生成流程，可以用元数据驱动：

• 用JSON/YAML定义函数和返回码的关联元数据，明确每个函数可能返回的RC值
• 生成Doxygen文档片段，直接注入到函数注释里
• 当被调用函数的返回码变更时，自动更新所有调用方的文档声明
• 优势：大幅降低手动维护成本，适合函数和返回码关系相对固定的项目
• 局限：需要额外维护元数据，对函数指针、虚函数这类动态调用场景支持有限

4. 编译期断言补充 #

结合宏和模板，在编译期做基础检查：

• 为每个函数定义一个包含所有允许返回码的std::set<RC>常量
• 在所有return语句处，用宏断言返回值属于这个集合
• 文档里同步维护这个集合的说明
• 优势：编译阶段就能发现未声明的返回码，不用额外工具
• 局限：没法自动处理间接调用的返回码，还是得手动更新集合

内容的提问来源于stack exchange，提问作者Eilon Kornboim