clang-format breaks doxygen content

[marcalff]

Bugzilla Link	44486
Version	unspecified
OS	Linux
CC	@marehr

Extended Description

Consider the following doxygen comment:

/**
  Some doxygen text.

  Part 1, ok to re format.

  @verbatim

  Part 2, should be left as is.

  @endverbatim

  Part 3, ok to reformat.

  Part 4 is UML below, should be left as is.

  @startuml
  Alice -> Bob: Authentication Request
  Bob --> Alice: Authentication Response

  Alice -> Bob: Another authentication Request
  Alice <-- Bob: Another authentication Response
  @enduml

  Part 5, ok to re format.
*/

When part 2 and 4 have long lines, which is very frequent, clang-format breaks the content when reformatting the text.

Even worse, the c++ code builds, and the doc may even build, producing garbage, so the break might go unnoticed.

I am aware of clang-format off/on, but this is not a good solution:

• using clang-format off/on for the entire comment disables too much.
• interleaving clang-format off/on inside doxygen blocks is too cumbersome, and might not even be possible in all cases.

I am aware of bug#19633, and I agree clang-format can not do much about it, since there is no markers in the use case for this bug.

Here however, the situation is different: there are existing markers in the source, so it would help to have clang-format honor them.

This feature request is to provide a way to tell clang-format about alternate strings to use instead 'clang-format off' / 'clang-format on' markers.

For example, with this entry in .clang-format:

Proposal: Alternate markers for 'clang-format off' ... 'clang-format on'

Formatting:

  - Off: '@verbatim'
    On: '@endverbatim'
  - Off: '@startuml'
    On: '@enduml'
  - Off: 'my-own-tool-begin-marker'
    On: 'my-own-tool-end-marker'

clang-format would turn off formatting when finding the '@verbatim' marker, and enable formatting when finding '@endverbatim', and likewise for UML.

Allowing end users to provide their own arbitrary markers helps to support any tool, not only doxygen.

Regards, -- Marc Alff

[rajkumarananthu]

Hi, I would like to work on this enhancement, can I, can you please assign the issue to me and provide any first hand inputs .

Thanks Rajkumar Ananthu

[steakhal]

I also had an issue with doxygen comments, in particular with this one:

  /// \copydoc clang::ento::CallDescription::matchesAny(const CallEvent &, const CallDescription &)
  template <typename... Ts>
  friend bool matchesAny(const CallEvent &Call, const CallDescription &CD1,
                         const Ts &...CDs) {
    return CD1.matches(Call) || matchesAny(Call, CDs...);
  }

Here clang-format would break the \copydoc line into this:

  /// \copydoc clang::ento::CallDescription::matchesAny(const CallEvent &, const
  /// CallDescription &)

I'm not entirely sure that it would break the \copydoc, but would definitely make it ugly. Consequently, I believe that clang-format should ignore lines containing the \copydoc marker.