[clang-format] Add option to decorate reflowed block comments

[apwadkar]

Summary

Added the DecorateReflowComments option to control whether '* ' are added
to the beginnings of continuation lines for block comments.

[MyDeveloperDay]

You need to regenerate the documentation after changing Format.h

[MyDeveloperDay]

You need to add unit tests

[apwadkar]

Sorry about the premature review, this is my first commit, and I didn't realize it wouldn't create a draft first.

• For rebuilding the docs, I assume I need to add -DLLVM_BUILD_DOCS=true to CMake and then run ninja -C build?

[MyDeveloperDay]

no you need to run

clang/doc/tools/dump_format_style.py

This will regnerate ClangFormatStyleOptions.rst from the Format.h change you have here, you then need to include that rst file in the review

[MyDeveloperDay]

clang/include/clang/Format/Format.h

2022

you are not setting the default value for this so it could be uninitialized, you need to set that in the LLVMStyle section

you need to ensure the == operator has been updated

you should be adding a CHECK_PARSE_BOOL() unit test at a minimum but also some verifyFormat checks in clang/unittest/Format

[HazardyKnusperkeks]

clang/lib/Format/BreakableToken.cpp

406

So if set to false it will never add the decoration. But when set to true it still will not, if it's the first line.

This is not what I'd expect reading the documentation.

If you want to pursue this I think you should go for an enum with Never, Always, and <insert name here> (what we currently have).

[apwadkar]

clang/lib/Format/BreakableToken.cpp

406

So if set to false it will never add the decoration. But when set to true it still will not, if it's the first line.

This is not what I'd expect reading the documentation.

Yeah, I think that makes sense. That's what I was thinking while working on the unit tests, because I realized this was breaking the existing style.

clang/include/clang/Format/Format.h

   ///    vector<int> x{1, 2, 3, 4};     vs.     vector<int> x{ 1, 2, 3, 4 };
   ///    vector<T> x{{}, {}, {}, {}};           vector<T> x{ {}, {}, {}, {} };
   ///    f(MyMap[{composite, key}]);            f(MyMap[{ composite, key }]);
   ///    new int[3]{1, 2, 3};                   new int[3]{ 1, 2, 3 };
   /// \endcode
   /// \version 3.4
   bool Cpp11BracedListStyle;
 
+  /// If ``true``, when a block comment is reflowed, add a ``* `` to the
+  /// beginning of the continuation line.
+  /// \code
+  ///     false:
+  ///     /* blah blah blah blah blah blah blah blah blah blah blah blah blah
+  ///        blah blah blah blah blah blah blah blah */
+  ///
+  ///     true:
+  ///     /* blah blah blah blah blah blah blah blah blah blah blah blah blah
+  ///      * blah blah blah blah blah blah blah blah */
+  /// \endcode
+  /// \version 17
+  bool DecorateReflowedComments;
+
   /// This option is **deprecated**. See ``DeriveLF`` and ``DeriveCRLF`` of
   /// ``LineEnding``.
   /// \version 10
   // bool DeriveLineEnding;
 
   /// If ``true``, analyze the formatted file for the most common
   /// alignment of ``&`` and ``*``.
   /// Pointer and reference alignment styles are going to be updated according

clang/lib/Format/BreakableToken.cpp

BreakableBlockComment::BreakableBlockComment(
   // ** blah blah blah
   // */
   if (Lines.size() >= 2 && Content[1].startswith("**") &&
       static_cast<unsigned>(ContentColumn[1]) == StartColumn) {
     DecorationColumn = StartColumn;
   }
 
   Decoration = "* ";
-  if (Lines.size() == 1 && !FirstInLine) {
+  if ((Lines.size() == 1 && !FirstInLine) || !Style.DecorateReflowedComments) {
     // Comments for which FirstInLine is false can start on arbitrary column,
     // and available horizontal space can be too small to align consecutive
     // lines with the first one.
     // FIXME: We could, probably, align them to current indentation level, but
     // now we just wrap them without stars.
     Decoration = "";
   }
   for (size_t i = 1, e = Content.size(); i < e && !Decoration.empty(); ++i) {

clang/lib/Format/Format.cpp

static void mapping(IO &IO, FormatStyle &Style) {
     IO.mapOptional("BreakStringLiterals", Style.BreakStringLiterals);
     IO.mapOptional("ColumnLimit", Style.ColumnLimit);
     IO.mapOptional("CommentPragmas", Style.CommentPragmas);
     IO.mapOptional("CompactNamespaces", Style.CompactNamespaces);
     IO.mapOptional("ConstructorInitializerIndentWidth",
                    Style.ConstructorInitializerIndentWidth);
     IO.mapOptional("ContinuationIndentWidth", Style.ContinuationIndentWidth);
     IO.mapOptional("Cpp11BracedListStyle", Style.Cpp11BracedListStyle);
+    IO.mapOptional("DecorateReflowedComments", Style.DecorateReflowedComments);
     IO.mapOptional("DerivePointerAlignment", Style.DerivePointerAlignment);
     IO.mapOptional("DisableFormat", Style.DisableFormat);
     IO.mapOptional("EmptyLineAfterAccessModifier",
                    Style.EmptyLineAfterAccessModifier);
     IO.mapOptional("EmptyLineBeforeAccessModifier",
                    Style.EmptyLineBeforeAccessModifier);
     IO.mapOptional("ExperimentalAutoDetectBinPacking",
                    Style.ExperimentalAutoDetectBinPacking);