[llvm-bugs] [Bug 44486] New: clang-format breaks doxygen content

[via llvm-bugs]

https://bugs.llvm.org/show_bug.cgi?id=44486

            Bug ID: 44486
           Summary: clang-format breaks doxygen content
           Product: clang
           Version: unspecified
          Hardware: PC
                OS: Linux
            Status: NEW
          Severity: enhancement
          Priority: P
         Component: Formatter
          Assignee: unassignedclangbugs at nondot.org
          Reporter: marc.alff at oracle.com
                CC: djasper at google.com, klimek at google.com,
                    llvm-bugs at lists.llvm.org

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

-- 
You are receiving this mail because:
You are on the CC list for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-bugs/attachments/20200108/17020948/attachment-0001.html>