如何高效检测自定义Doxygen标签及非Doxygen注释的错误用法？

以下是几种比手动文本解析更便捷高效的方法，既能覆盖Doxygen标签检查，也能适配非Doxygen注释场景：

1. 利用Doxygen自身的警告机制 #

Doxygen自带文档错误检测能力，只需调整Doxyfile配置参数，就能自动识别标签格式错误：

• 开启WARN_IF_DOC_ERROR = YES，强制Doxygen输出文档解析时的警告信息；
• 设置WARN_AS_ERROR = YES，将文档错误转为编译级错误，在CI流程中直接阻断不符合规范的代码提交；
• 自定义标签如@mytag后带空格（@mytag {xxx}）时，Doxygen会将@mytag识别为普通文本而非命令，这类问题会直接出现在警告日志中；
• 对于\reqtest的错误写法（如\ reqtest{...}、\reqtest{...}\n），Doxygen无法识别为合法命令，同样会触发警告。

运行Doxygen后，查看输出日志或通过WARN_LOGFILE指定的警告文件，即可定位所有格式错误的标签。

2. 自定义静态代码分析规则 #

使用Clang-Tidy这类静态分析工具，编写自定义检查规则精准匹配标签错误：

• 基于Clang的AST解析能力，遍历代码中的注释节点；
• 编写针对性的正则匹配逻辑，比如：
  • 匹配@mytag\s+{（@mytag后带空格的错误写法）；
  • 匹配\\\s+reqtest{（\reqtest前多空格的错误写法）；
  • 匹配\\reqtest\{.*?(\\n|@n)（\reqtest内容后带\n或@n的错误写法）；
• 将自定义规则集成到CI/CD流程或IDE（如CLion、VS Code）中，实现实时检测。

3. 注释专用Lint脚本+正则匹配 #

编写专用Lint脚本结合正则表达式，批量检查所有头文件的注释：

• 用Python/Shell脚本遍历目标文件，提取注释块内容；
• 编写精准正则匹配各类错误场景，示例Python代码片段：

  import re
  
  # 匹配@mytag后带空格的错误
  mytag_error = re.compile(r'@mytag\s+{')
  # 匹配\reqtest的各类错误写法
  reqtest_errors = [
      re.compile(r'\\\s+reqtest{'),
      re.compile(r'\\reqtest\{.*?\\n'),
      re.compile(r'\\reqtest\{.*?@n')
  ]
  
  # 遍历文件、匹配错误并输出位置的逻辑...
  

• 这类脚本可灵活扩展规则，适配非Doxygen注释的自定义标签规范，还能直接输出错误的文件名和行号，方便快速定位。

4. IDE自定义实时检查 #

在常用IDE中配置自定义检查规则，实现编辑时的实时错误提示：

• JetBrains系列IDE（如CLion）：通过「Settings → Editor → Inspections → Custom Inspection」添加正则匹配规则，针对注释文本检测错误标签；
• VS Code：借助正则查找插件结合任务配置，在保存文件时自动检查并弹出错误提示。

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