如何设置 clang 格式的注释编译指示，这样多行 doxygen 注释就不会被触及？

Question

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

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

处理

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

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

到目前为止，我所能做的就是保留多行注释的第一行，如果它恰好超过了列数限制。但是，任何后续的长线仍然被打断。

我唯一留在我的盒子里的其他工具是使用 // clang-format off 和 // clang-format on 围绕这些评论，但我还是想尽可能避免它，因为：

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

b) 我将不得不用这些来包围整个评论，而不仅仅是逐字块（我还没有想出你是否可以只为多行评论的一部分禁用它 - 我'我们只设法让它为整个文件工作，即使那是可能的，clang-format 指令最终也会出现在生成的 Doxygen 文档中，这是不可接受的）

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

感谢任何帮助。谢谢。

Answer 1

运行也进入这个问题，唯一的解决方法是使用 clang-format on/off.

clang-format 回流评论倾向于：

打破 @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

如何设置 clang 格式的注释编译指示，这样多行 doxygen 注释就不会被触及？

How to set up clang-format comment pragmas so multiline doxygen comments don't get touched?

c

c++

doxygen

clang-format