我正在尝试将clang-format引入我们工作中的一些项目(C和C++),但我无法按照我想要的方式格式化多行Doxygen注释。
所有注释都有相同的格式:
/*! @brief Some text
*
* Some more text
*
* @verbatim
*
* A very long line of text that exceeds the clang-format column width but should not be touched
*
* @endverbatim
*/
我希望 clang-format 保留 verbatim 块并不对其进行重新格式化。我正在使用 clang-format-6.0。
关闭 `ReflowComments` 不是一个选项,因为 clang-format 必须处理非 Doxygen 注释。
我已经尝试了各种正则表达式在 `CommentPragmas` 配置项中,但都无济于事:
- 使用 `@verbatim(.*\n)*.*@endverbatim` 将整个 verbatim 块作为注释 pragma 处理。这是理想的情况,因为我不介意 Doxygen 注释的任何其他部分被拆成多行。 - 使用 `@brief(.*\n)+` 匹配整个注释块作为 pragma。我还尝试了在注释结尾加上一个任意标记来充当显式的块结束标记。这不是理想的,因为它不能迫使注释的非 verbatim 部分符合要求,但如果必须这样做,则我愿意接受这种妥协。 - 还有其他一些我在其他讨论中看到过的正则表达式,可以适应我们的 Doxygen 标记。
到目前为止,我所能做的就是让 clang-format 保留多行注释的第一行,如果它超过列限制。然而,任何后续的长行仍然会被拆分。
唯一剩下的工具是在这些注释周围使用 `// clang-format off` 和 `// clang-format on`,但我想尽量避免这样做,因为:
- 在整个代码库中添加它们会很麻烦。 - 我必须将整个注释都用上述指令括起来,而不仅仅是 verbatim 块(我还没有弄清楚是否可以仅对多行注释的一部分禁用 clang-format,我只成功地让它适用于整个注释。而且,即使这是可能的,clang-format 指令也最终会出现在生成的 Doxygen 文档中,这是不可接受的)。 - 我真的不喜欢它在代码中的外观。
感谢任何帮助。谢谢。