如何设置 clang 格式的注释 pragma，以免触及多行 doxygen 注释？

Question

我正在尝试将 clang-format 引入我们工作中的几个项目（C 和 C++），但我无法让它以我想要的方式格式化多行 Doxygen cmets。

所有 cmets 格式相同：

/*! @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 单独保留逐字块而不是重排它们。我正在使用 clang-format-6.0

关闭 ReflowComments 不是一个选项，因为非 doxygen cmets 必须由 clang-format 处理

我在CommentPragmas 配置项中尝试了各种正则表达式，但无济于事：

• @verbatim(.*\n)*.*@endverbatim 将整个逐字块视为注释杂注。这是理想的情况，因为我不介意将 Doxygen 评论的任何其他部分分成多行。
• @brief(.*\n)+ 匹配整个注释块作为编译指示。我还尝试在注释末尾使用任意标记来充当显式的块结束标记。这并不理想，因为它不会强制评论的非逐字部分符合，但如果必须，我愿意接受的妥协。
• 我在其他讨论中看到的各种其他正则表达式，已适应我们的 Doxygen 标记。

到目前为止，我所做的只是将多行注释的第一行放在一边，如果它碰巧超过了列限制。但是，任何后续的长线仍然被打断。

我剩下的唯一其他工具是在这些 cmets 周围使用 // clang-format off 和 // clang-format on，但如果可以的话，我想再次避免使用它，因为：

a) 在整个代码库中添加它们会很乏味

b) 我必须用这些来包围整个 cmets，而不仅仅是逐字块（我还没有弄清楚你是否可以只为多行注释的一部分禁用它 - 我只有设法让它为整个系统工作，即使这是可能的，clang-format 指令最终会出现在生成的 Doxygen 文档中，这是不可接受的）

c) 我不太喜欢它在代码中的样子。

感谢任何帮助。谢谢。

Answer 1

也遇到了这个问题，找到的唯一解决方法是使用clang-format on/off。

clang-format reflow cmets 倾向于：

• 打破@page、@section等标题，以及从它们生成的链接（在极少数情况下）。
• 打破具有特定语法的@startuml 块。
• 打破@verbatim 块。

查看 MySQL 中的使用示例： https://github.com/mysql/mysql-server/blob/8.0/storage/perfschema/pfs.cc

更新：

针对 clang-format 本身提出了功能请求： https://bugs.llvm.org/show_bug.cgi?id=44486