[clang] [clang-format] Introduce "ReflowComments: IndentOnly" to re-indent comments without breaking internal structure (think Doxygen). (PR #96804)
Iuri Chaer via cfe-commits
cfe-commits at lists.llvm.org
Thu Aug 15 06:29:41 PDT 2024
================
@@ -5272,22 +5272,46 @@ the configuration (without a prefix: ``Auto``).
.. _ReflowComments:
-**ReflowComments** (``Boolean``) :versionbadge:`clang-format 3.8` :ref:`¶ <ReflowComments>`
- If ``true``, clang-format will attempt to re-flow comments. That is it
- will touch a comment and *reflow* long comments into new lines, trying to
- obey the ``ColumnLimit``.
+**ReflowComments** (``ReflowCommentsStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <ReflowComments>`
+ Comment reformatting style.
- .. code-block:: c++
+ Possible values:
+
+ * ``RCS_Never`` (in configuration: ``Never``)
+ Leave comments untouched.
+
+ .. code-block:: c++
+
+ // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+ /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ * and a misaligned second line */
+
+ * ``RCS_IndentOnly`` (in configuration: ``IndentOnly``)
+ Only apply indentation rules, moving comments left or right, without
+ changing formatting inside the comments.
+
+ .. code-block:: c++
+
+ // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+ /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ * and a misaligned second line */
+
+ * ``RCS_Always`` (in configuration: ``Always``)
+ Apply indentation rules and re-flow long comments into new lines, trying
----------------
ichaer wrote:
Oh man, I remembered it while making the changes and then forgot before committing =(
Have you considered adding that to the build system and perhaps also a CI test? It must be tricky for reviewers, having to remember to check this stuff every time, and the additional review roundtrips... I can propose a separate PR that introduces something like this to `clang/docs/CMakeLists.txt`:
```
add_custom_target(clang-format-style-options
COMMAND "${Python3_EXECUTABLE}" dump_format_style.py
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/tools"
DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/../include/clang/Format/Format.h")
add_dependencies(clang-format clang-format-style-options)
```
And maybe add the `clang-format-style-options` target to `.github/workflows/docs.yml`, with a validation that `git status --porcelain clang/docs/ClangFormatStyleOptions.rst` returns an empty output. If this is something you think could help reduce the burden on reviewers.
https://github.com/llvm/llvm-project/pull/96804
More information about the cfe-commits
mailing list