c++ - 如何设置 clang-format 注释 pragmas 以便多行 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 保留逐字 block 而不是回流它们。我正在使用 clang-format-6.0

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

我在CommentPragmas配置项中尝试了各种正则表达式，但没有效果:

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

到目前为止，我所做的就是保留多行注释的第一行(如果它碰巧超出了列限制)。然而，任何后续的长线仍然被打破。

我留在盒子里的唯一其他工具是在这些评论周围使用 //clang-format off 和 //clang-format on 但我再次'如果可以的话我想避免它，因为:

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

b)我必须用这些内容包围整个注释，而不仅仅是逐字 block (我还没有弄清楚是否可以仅针对多行注释的一部分禁用它 - 我只设法让它在整个系统中工作，即使这是可能的，clang-format 指令最终也会出现在生成的 Doxygen 文档中，这是 Not Acceptable )

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

感谢任何帮助。谢谢。

Answer 1

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

clang-format 重新流动的评论倾向于:

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

查看 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