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

Question

I am trying to introduce clang-format to a couple of our projects at work (C and C++), but I am having trouble getting it to format multi-line Doxygen comments the way I want.

All comments have the same format:

/*! @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
 */

I want clang-format to leave the verbatim blocks alone and not reflow them. I am using clang-format-6.0

Turning ReflowComments off is not an option as non-doxygen comments must be taken care of by clang-format

I have tried various regular expressions in the CommentPragmas config item but to no avail:

• @verbatim(.*\\n)*.*@endverbatim to treat the entire verbatim block as a comment pragma. This is the ideal situation, as any other part of the Doxygen comment I do not mind being broken into multiple lines.
• @brief(.*\\n)+ to match the entire comment block as the pragma. I've also tried this with an arbitrary token at the end of the comment to act as an explicit end-of-block marker. This isn't ideal as it doesn't force the non-verbatim part of the comment to conform, but is a compromise I'm willing to live with if I have to.
• Various other regexes I've seen in other discussions, adapted to fit our Doxygen markup.

All I've managed to get it to do so far is to leave the first line of the multi-line comment alone, if it happens to exceed the column limit. However, any following long line is still broken up.

The only other tool I have left in my box is to use // clang-format off and // clang-format on around these comments but again I'd like to avoid it if I can because:

a) it'll be quite tedious to add them throughout the code base

b) I'll have to surround the entire comments with these, rather than just the verbatim blocks (I haven't figured out if you can disable it just for a portion of a multi-line comment - I've only managed to get it working for an entire one, and even if that was possible the clang-format directives would end up in the generated Doxygen docs which is unacceptable)

c) I don't really like the way it looks in code.

Any help is appreciated. Thanks.

Answer 1

Ran into this issue also, and the only work around found was to use clang-format on/off .

clang-format re flowing comments tends to:

• break @page , @section , etc titles, and links generated from them (in rare cases).
• break @startuml blocks, which have a specific syntax.
• break @verbatim blocks.

See an example of usage in MySQL: https://github.com/mysql/mysql-server/blob/8.0/storage/perfschema/pfs.cc

Update:

Filed a feature request on clang-format itself: https://bugs.llvm.org/show_bug.cgi?id=44486