如何在CI中配置Doxygen，仅对新增代码触发文档校验失败？

Doxygen本身没有原生支持只针对新增代码触发文档警告的配置，但可以结合CI流程和版本控制工具（比如Git）来实现这个需求，具体有两种可行方案：

方法一：限定Doxygen仅扫描新增/修改的文件 #

1. 提取变更文件列表：在CI脚本中用Git命令获取当前提交相对于基线分支（比如主分支main）的C++源文件/头文件变更：

   # 筛选出新增/修改的.cpp/.h/.hpp文件，保存到列表中
   git diff --name-only main...HEAD | grep -E "\.(cpp|h|hpp)$" > changed_files.txt
   

2. 配置Doxygen扫描范围：修改Doxyfile，开启文档警告并将扫描范围限定为变更文件：

   WARN_IF_UNDOCUMENTED = YES
   WARN_AS_ERROR = YES
   # 读取变更文件列表作为扫描输入（部分Doxygen版本支持@语法）
   INPUT = @changed_files.txt
   

   若你的Doxygen版本不支持@filename语法，可以在CI脚本中直接拼接文件路径到INPUT配置项。
3. CI执行检查：先生成变更文件列表，再运行Doxygen，新增代码若存在未文档化内容，Doxygen会触发错误导致CI失败。

方法二：过滤Doxygen警告到仅变更文件 #

如果需要保留Doxygen对全量代码的扫描（比如依赖现有代码的文档上下文），可以先生成全量警告，再筛选出仅属于变更文件的警告：

1. 捕获Doxygen警告：运行Doxygen并将警告输出到文件：

   doxygen Doxyfile 2> doxygen_warnings.txt
   

2. 获取变更文件列表：同方法一的Git命令生成changed_files.txt。
3. 筛选并检查警告：遍历变更文件，检查是否有对应的警告存在，若有则终止CI流程：

   for file in $(cat changed_files.txt); do
     if grep -q "$file" doxygen_warnings.txt; then
       echo "新增/修改文件 $file 存在未文档化内容"
       exit 1
     fi
   done
   

注意事项 #

• 基线分支可根据CI场景调整：比如PR检查时，应对比目标分支与PR分支的差异；
• 可根据项目文件类型调整grep的正则表达式，覆盖所有需要检查的代码文件；
• 若项目包含自动生成代码，需在Git差异过滤或Doxygen配置中排除这些文件；
• 提前测试Doxygen版本兼容性，确保INPUT的文件列表语法可用。

内容的提问来源于stack exchange，提问作者Tom Penard