clang-tidy错误解析含@ref的@see类doxygen注释问题咨询

问题根因 #

该报错是Doxygen和clang-tidy的Doxygen语法解析规则存在兼容差异导致的，既不是你的注释写法违反Doxygen规范，也不是clang-tidy完全无意义的误判：

• 你写的/// @see @ref Foo::Bar()完全符合Doxygen官方语法规范：Doxygen允许@see命令后直接跟随@ref引用作为内容，可以正常生成跳转链接属于预期行为。
• Clang-tidy的Doxygen检测模块对@see命令的参数解析逻辑更严格：它默认要求@see后必须紧跟可识别的文本内容，会把开头的@ref识别为独立命令而非@see的内容参数，因此误判@see后没有有效段落内容，抛出对应错误。

兼容修复方案 #

以下两种写法都可以同时满足Doxygen生成跳转链接的需求，也不会触发clang-tidy报错：

• 省略冗余的@ref标记：Doxygen的@see命令本身支持直接跟随符号名自动生成跳转，直接修改为/// @see Foo::Bar()即可，两种工具都可以正常识别。
• 为@ref补充显式链接文本：如果需要自定义链接的显示内容，可以修改为/// @see @ref Foo::Bar() "Foo类的Bar方法"，补充文本内容后clang-tidy即可识别到@see的有效内容，不再触发报错。

内容的提问来源于stack exchange，提问作者Stéphane