如何设置叮当格式的注释编译指示，以免触及多行doxygen注释？

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

本文关键字：注释 doxygen 指示 编译 何设置 设置 格式 叮当      更新时间：2023-10-16

我正在尝试将 clang 格式引入我们工作中的几个项目(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 格式保留逐字块而不重排它们。我正在使用 clang-format-6.0

关闭ReflowComments不是一种选择，因为非doxygen注释必须通过clang格式处理

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

  • @verbatim(.*n)*.*@endverbatim将整个逐字记录块视为注释杂注。这是理想的情况，因为 Doxygen 评论的任何其他部分我不介意被分成多行。
  • @brief(.*n)+将整个注释块匹配为杂注。我还尝试在评论末尾使用任意令牌来充当明确的块结束标记。这并不理想，因为它不会强制评论的非逐字部分保持一致，但如果有必要，这是我愿意接受的妥协。
  • 我在其他讨论中看到的各种其他正则表达式，适应了我们的 Doxygen 标记。

到目前为止，我设法让它做的只是保留多行评论的第一行，如果它碰巧超过列限制。但是，任何后续的长线仍然被打破。

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

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

b( 我将不得不用这些包围整个评论，而不仅仅是逐字块(我还没有弄清楚您是否可以仅针对多行评论的一部分禁用它 - 我只设法让它适用于整个评论，即使有可能，clang格式指令最终也会出现在生成的 Doxygen 文档中，这是不可接受的(

c( 我不太喜欢它在代码中的外观。

任何帮助，不胜感激。谢谢。

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

CLANG 格式的重新流动注释倾向于：

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

请参阅MySQL中的用法示例： https://github.com/mysql/mysql-server/blob/8.0/storage/perfschema/pfs.cc

更新：

在 clang 格式本身上提交了功能请求： https://bugs.llvm.org/show_bug.cgi?id=44486

相关文章：