<html>
<head>
<base href="https://bugs.llvm.org/">
</head>
<body><table border="1" cellspacing="0" cellpadding="8">
<tr>
<th>Bug ID</th>
<td><a class="bz_bug_link
bz_status_NEW "
title="NEW - clang-format breaks doxygen content"
href="https://bugs.llvm.org/show_bug.cgi?id=44486">44486</a>
</td>
</tr>
<tr>
<th>Summary</th>
<td>clang-format breaks doxygen content
</td>
</tr>
<tr>
<th>Product</th>
<td>clang
</td>
</tr>
<tr>
<th>Version</th>
<td>unspecified
</td>
</tr>
<tr>
<th>Hardware</th>
<td>PC
</td>
</tr>
<tr>
<th>OS</th>
<td>Linux
</td>
</tr>
<tr>
<th>Status</th>
<td>NEW
</td>
</tr>
<tr>
<th>Severity</th>
<td>enhancement
</td>
</tr>
<tr>
<th>Priority</th>
<td>P
</td>
</tr>
<tr>
<th>Component</th>
<td>Formatter
</td>
</tr>
<tr>
<th>Assignee</th>
<td>unassignedclangbugs@nondot.org
</td>
</tr>
<tr>
<th>Reporter</th>
<td>marc.alff@oracle.com
</td>
</tr>
<tr>
<th>CC</th>
<td>djasper@google.com, klimek@google.com, llvm-bugs@lists.llvm.org
</td>
</tr></table>
<p>
<div>
<pre>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 <a class="bz_bug_link
bz_status_RESOLVED bz_closed"
title="RESOLVED WONTFIX - clang-format breaks doxygen tables"
href="show_bug.cgi?id=19633">bug#19633</a>, 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</pre>
</div>
</p>
<hr>
<span>You are receiving this mail because:</span>
<ul>
<li>You are on the CC list for the bug.</li>
</ul>
</body>
</html>