[clang] 0fba838 - [clang-format] Introduce "ReflowComments: IndentOnly" to re-indent comments without breaking internal structure (think Doxygen). (#96804)
via cfe-commits
cfe-commits at lists.llvm.org
Fri Oct 11 19:14:13 PDT 2024
Author: Iuri Chaer
Date: 2024-10-11T19:14:09-07:00
New Revision: 0fba8381d2a71ff440fdf0ae30d59a0bf07fea75
URL: https://github.com/llvm/llvm-project/commit/0fba8381d2a71ff440fdf0ae30d59a0bf07fea75
DIFF: https://github.com/llvm/llvm-project/commit/0fba8381d2a71ff440fdf0ae30d59a0bf07fea75.diff
LOG: [clang-format] Introduce "ReflowComments: IndentOnly" to re-indent comments without breaking internal structure (think Doxygen). (#96804)
* Convert `ReflowComments` from boolean into a new `enum` which can take
on the value `RCS_Never`, `RCS_IndentOnly`, or `RCS_Always`. The first
one is equivalent to the old `false`, the third one is `true`, and the
middle one means that multiline comments should only have their
indentation corrected, which is what Doxygen users will want.
* Preserve backward compatibility while parsing `ReflowComments`.
Added:
Modified:
clang/docs/ClangFormatStyleOptions.rst
clang/docs/ReleaseNotes.rst
clang/include/clang/Format/Format.h
clang/lib/Format/BreakableToken.cpp
clang/lib/Format/BreakableToken.h
clang/lib/Format/ContinuationIndenter.cpp
clang/lib/Format/Format.cpp
clang/lib/Format/UnwrappedLineParser.cpp
clang/unittests/Format/ConfigParseTest.cpp
clang/unittests/Format/FormatTest.cpp
clang/unittests/Format/FormatTestComments.cpp
Removed:
################################################################################
diff --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst
index a9bfb4c4a0fcb2..8add0a53e5be13 100644
--- a/clang/docs/ClangFormatStyleOptions.rst
+++ b/clang/docs/ClangFormatStyleOptions.rst
@@ -5406,22 +5406,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 reflow long comments into new lines, trying
+ to obey the ``ColumnLimit``.
+
+ .. 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 */
- false:
- // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
- /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
- true:
- // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
- // information
- /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
- * information */
.. _RemoveBracesLLVM:
diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 69f02fb0910177..337e3fc10bf49d 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -663,6 +663,8 @@ clang-format
- Adds ``BreakBinaryOperations`` option.
- Adds ``TemplateNames`` option.
- Adds ``AlignFunctionDeclarations`` option to ``AlignConsecutiveDeclarations``.
+- Adds ``IndentOnly`` suboption to ``ReflowComments`` to fix the indentation of multi-line comments
+ without touching their contents, renames ``false`` to ``Never``, and ``true`` to ``Always``.
libclang
--------
diff --git a/clang/include/clang/Format/Format.h b/clang/include/clang/Format/Format.h
index 3d3e4330902a30..a0762b088b68ef 100644
--- a/clang/include/clang/Format/Format.h
+++ b/clang/include/clang/Format/Format.h
@@ -3847,24 +3847,43 @@ struct FormatStyle {
ReferenceAlignmentStyle ReferenceAlignment;
// clang-format off
- /// 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``.
- /// \code
- /// false:
- /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
- /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
- ///
- /// true:
- /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
- /// // information
- /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
- /// * information */
- /// \endcode
- /// \version 3.8
- bool ReflowComments;
+ /// \brief Types of comment reflow style.
+ enum ReflowCommentsStyle : int8_t {
+ /// Leave comments untouched.
+ /// \code
+ /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+ /// /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /// * and a misaligned second line */
+ /// \endcode
+ RCS_Never,
+ /// Only apply indentation rules, moving comments left or right, without
+ /// changing formatting inside the comments.
+ /// \code
+ /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+ /// /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /// * and a misaligned second line */
+ /// \endcode
+ RCS_IndentOnly,
+ /// Apply indentation rules and reflow long comments into new lines, trying
+ /// to obey the ``ColumnLimit``.
+ /// \code
+ /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ /// // information
+ /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ /// * information */
+ /// /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ /// * information and a misaligned second line */
+ /// \endcode
+ RCS_Always
+ };
// clang-format on
+ /// \brief Comment reformatting style.
+ /// \version 3.8
+ ReflowCommentsStyle ReflowComments;
+
/// Remove optional braces of control statements (``if``, ``else``, ``for``,
/// and ``while``) in C++ according to the LLVM coding style.
/// \warning
diff --git a/clang/lib/Format/BreakableToken.cpp b/clang/lib/Format/BreakableToken.cpp
index 75304908dc6506..bde77578769906 100644
--- a/clang/lib/Format/BreakableToken.cpp
+++ b/clang/lib/Format/BreakableToken.cpp
@@ -420,7 +420,7 @@ BreakableComment::getSplit(unsigned LineIndex, unsigned TailOffset,
unsigned ColumnLimit, unsigned ContentStartColumn,
const llvm::Regex &CommentPragmasRegex) const {
// Don't break lines matching the comment pragmas regex.
- if (CommentPragmasRegex.match(Content[LineIndex]))
+ if (!AlwaysReflow || CommentPragmasRegex.match(Content[LineIndex]))
return Split(StringRef::npos, 0);
return getCommentSplit(Content[LineIndex].substr(TailOffset),
ContentStartColumn, ColumnLimit, Style.TabWidth,
@@ -608,7 +608,7 @@ BreakableToken::Split BreakableBlockComment::getSplit(
unsigned LineIndex, unsigned TailOffset, unsigned ColumnLimit,
unsigned ContentStartColumn, const llvm::Regex &CommentPragmasRegex) const {
// Don't break lines matching the comment pragmas regex.
- if (CommentPragmasRegex.match(Content[LineIndex]))
+ if (!AlwaysReflow || CommentPragmasRegex.match(Content[LineIndex]))
return Split(StringRef::npos, 0);
return getCommentSplit(Content[LineIndex].substr(TailOffset),
ContentStartColumn, ColumnLimit, Style.TabWidth,
@@ -855,7 +855,8 @@ bool BreakableBlockComment::mayReflow(
StringRef IndentContent = Content[LineIndex];
if (Lines[LineIndex].ltrim(Blanks).starts_with("*"))
IndentContent = Lines[LineIndex].ltrim(Blanks).substr(1);
- return LineIndex > 0 && !CommentPragmasRegex.match(IndentContent) &&
+ return LineIndex > 0 && AlwaysReflow &&
+ !CommentPragmasRegex.match(IndentContent) &&
mayReflowContent(Content[LineIndex]) && !Tok.Finalized &&
!switchesFormatting(tokenAt(LineIndex));
}
@@ -1160,7 +1161,8 @@ bool BreakableLineCommentSection::mayReflow(
// // text that protrudes
// // into text with
diff erent indent
// We do reflow in that case in block comments.
- return LineIndex > 0 && !CommentPragmasRegex.match(IndentContent) &&
+ return LineIndex > 0 && AlwaysReflow &&
+ !CommentPragmasRegex.match(IndentContent) &&
mayReflowContent(Content[LineIndex]) && !Tok.Finalized &&
!switchesFormatting(tokenAt(LineIndex)) &&
OriginalPrefix[LineIndex] == OriginalPrefix[LineIndex - 1];
diff --git a/clang/lib/Format/BreakableToken.h b/clang/lib/Format/BreakableToken.h
index 8b9360a3335ef4..45c00b35fd01ed 100644
--- a/clang/lib/Format/BreakableToken.h
+++ b/clang/lib/Format/BreakableToken.h
@@ -384,6 +384,8 @@ class BreakableComment : public BreakableToken {
// The intended start column of the first line of text from this section.
unsigned StartColumn;
+ const bool AlwaysReflow = Style.ReflowComments == FormatStyle::RCS_Always;
+
// The prefix to use in front a line that has been reflown up.
// For example, when reflowing the second line after the first here:
// // comment 1
diff --git a/clang/lib/Format/ContinuationIndenter.cpp b/clang/lib/Format/ContinuationIndenter.cpp
index 4df8dc89be459f..fd53969e4b3b33 100644
--- a/clang/lib/Format/ContinuationIndenter.cpp
+++ b/clang/lib/Format/ContinuationIndenter.cpp
@@ -2471,7 +2471,7 @@ ContinuationIndenter::createBreakableToken(const FormatToken &Current,
State.Line->InPPDirective, Encoding, Style);
}
} else if (Current.is(TT_BlockComment)) {
- if (!Style.ReflowComments ||
+ if (Style.ReflowComments == FormatStyle::RCS_Never ||
// If a comment token switches formatting, like
// /* clang-format on */, we don't want to break it further,
// but we may still want to adjust its indentation.
@@ -2492,7 +2492,7 @@ ContinuationIndenter::createBreakableToken(const FormatToken &Current,
}
return true;
}();
- if (!Style.ReflowComments ||
+ if (Style.ReflowComments == FormatStyle::RCS_Never ||
CommentPragmasRegex.match(Current.TokenText.substr(2)) ||
switchesFormatting(Current) || !RegularComments) {
return nullptr;
diff --git a/clang/lib/Format/Format.cpp b/clang/lib/Format/Format.cpp
index f97127f09d2096..148270795c562f 100644
--- a/clang/lib/Format/Format.cpp
+++ b/clang/lib/Format/Format.cpp
@@ -527,6 +527,17 @@ template <> struct MappingTraits<FormatStyle::RawStringFormat> {
}
};
+template <> struct ScalarEnumerationTraits<FormatStyle::ReflowCommentsStyle> {
+ static void enumeration(IO &IO, FormatStyle::ReflowCommentsStyle &Value) {
+ IO.enumCase(Value, "Never", FormatStyle::RCS_Never);
+ IO.enumCase(Value, "IndentOnly", FormatStyle::RCS_IndentOnly);
+ IO.enumCase(Value, "Always", FormatStyle::RCS_Always);
+ // For backward compatibility:
+ IO.enumCase(Value, "false", FormatStyle::RCS_Never);
+ IO.enumCase(Value, "true", FormatStyle::RCS_Always);
+ }
+};
+
template <>
struct ScalarEnumerationTraits<FormatStyle::ReferenceAlignmentStyle> {
static void enumeration(IO &IO, FormatStyle::ReferenceAlignmentStyle &Value) {
@@ -1569,7 +1580,7 @@ FormatStyle getLLVMStyle(FormatStyle::LanguageKind Language) {
LLVMStyle.PPIndentWidth = -1;
LLVMStyle.QualifierAlignment = FormatStyle::QAS_Leave;
LLVMStyle.ReferenceAlignment = FormatStyle::RAS_Pointer;
- LLVMStyle.ReflowComments = true;
+ LLVMStyle.ReflowComments = FormatStyle::RCS_Always;
LLVMStyle.RemoveBracesLLVM = false;
LLVMStyle.RemoveParentheses = FormatStyle::RPS_Leave;
LLVMStyle.RemoveSemicolon = false;
diff --git a/clang/lib/Format/UnwrappedLineParser.cpp b/clang/lib/Format/UnwrappedLineParser.cpp
index 9c4a065fd93b96..c9625c39e527b4 100644
--- a/clang/lib/Format/UnwrappedLineParser.cpp
+++ b/clang/lib/Format/UnwrappedLineParser.cpp
@@ -4623,9 +4623,9 @@ bool UnwrappedLineParser::isOnNewLine(const FormatToken &FormatTok) {
// section on \p Line.
static bool
continuesLineCommentSection(const FormatToken &FormatTok,
- const UnwrappedLine &Line,
+ const UnwrappedLine &Line, const FormatStyle &Style,
const llvm::Regex &CommentPragmasRegex) {
- if (Line.Tokens.empty())
+ if (Line.Tokens.empty() || Style.ReflowComments != FormatStyle::RCS_Always)
return false;
StringRef IndentContent = FormatTok.TokenText;
@@ -4738,7 +4738,7 @@ void UnwrappedLineParser::flushComments(bool NewlineBeforeNext) {
// FIXME: Consider putting separate line comment sections as children to the
// unwrapped line instead.
Tok->ContinuesLineCommentSection =
- continuesLineCommentSection(*Tok, *Line, CommentPragmasRegex);
+ continuesLineCommentSection(*Tok, *Line, Style, CommentPragmasRegex);
if (isOnNewLine(*Tok) && JustComments && !Tok->ContinuesLineCommentSection)
addUnwrappedLine();
pushToken(Tok);
@@ -4811,8 +4811,8 @@ void UnwrappedLineParser::distributeComments(
if (HasTrailAlignedWithNextToken && i == StartOfTrailAlignedWithNextToken) {
FormatTok->ContinuesLineCommentSection = false;
} else {
- FormatTok->ContinuesLineCommentSection =
- continuesLineCommentSection(*FormatTok, *Line, CommentPragmasRegex);
+ FormatTok->ContinuesLineCommentSection = continuesLineCommentSection(
+ *FormatTok, *Line, Style, CommentPragmasRegex);
}
if (!FormatTok->ContinuesLineCommentSection &&
(isOnNewLine(*FormatTok) || FormatTok->IsFirst)) {
diff --git a/clang/unittests/Format/ConfigParseTest.cpp b/clang/unittests/Format/ConfigParseTest.cpp
index 9abb8a110bf8ee..318f08c04759b9 100644
--- a/clang/unittests/Format/ConfigParseTest.cpp
+++ b/clang/unittests/Format/ConfigParseTest.cpp
@@ -183,7 +183,6 @@ TEST(ConfigParseTest, ParsesConfigurationBools) {
CHECK_PARSE_BOOL(ObjCSpaceAfterProperty);
CHECK_PARSE_BOOL(ObjCSpaceBeforeProtocolList);
CHECK_PARSE_BOOL(Cpp11BracedListStyle);
- CHECK_PARSE_BOOL(ReflowComments);
CHECK_PARSE_BOOL(RemoveBracesLLVM);
CHECK_PARSE_BOOL(RemoveSemicolon);
CHECK_PARSE_BOOL(SkipMacroDefinitionBody);
@@ -381,6 +380,16 @@ TEST(ConfigParseTest, ParsesConfiguration) {
CHECK_PARSE("PointerBindsToType: Middle", PointerAlignment,
FormatStyle::PAS_Middle);
+ Style.ReflowComments = FormatStyle::RCS_Always;
+ CHECK_PARSE("ReflowComments: Never", ReflowComments, FormatStyle::RCS_Never);
+ CHECK_PARSE("ReflowComments: IndentOnly", ReflowComments,
+ FormatStyle::RCS_IndentOnly);
+ CHECK_PARSE("ReflowComments: Always", ReflowComments,
+ FormatStyle::RCS_Always);
+ // For backward compatibility:
+ CHECK_PARSE("ReflowComments: false", ReflowComments, FormatStyle::RCS_Never);
+ CHECK_PARSE("ReflowComments: true", ReflowComments, FormatStyle::RCS_Always);
+
Style.Standard = FormatStyle::LS_Auto;
CHECK_PARSE("Standard: c++03", Standard, FormatStyle::LS_Cpp03);
CHECK_PARSE("Standard: c++11", Standard, FormatStyle::LS_Cpp11);
diff --git a/clang/unittests/Format/FormatTest.cpp b/clang/unittests/Format/FormatTest.cpp
index 2c5e5857445c35..43513f18321bc0 100644
--- a/clang/unittests/Format/FormatTest.cpp
+++ b/clang/unittests/Format/FormatTest.cpp
@@ -18108,7 +18108,7 @@ TEST_F(FormatTest, AlignConsecutiveMacros) {
// Test across comments
Style.MaxEmptyLinesToKeep = 10;
- Style.ReflowComments = false;
+ Style.ReflowComments = FormatStyle::RCS_Never;
Style.AlignConsecutiveMacros.AcrossComments = true;
verifyFormat("#define a 3\n"
"// line comment\n"
@@ -18855,7 +18855,7 @@ TEST_F(FormatTest, AlignConsecutiveAssignmentsAcrossEmptyLinesAndComments) {
"y = 1;",
Alignment);
- Alignment.ReflowComments = true;
+ Alignment.ReflowComments = FormatStyle::RCS_Always;
Alignment.ColumnLimit = 50;
verifyFormat("int x = 0;\n"
"int yy = 1; /// specificlennospace\n"
@@ -19253,7 +19253,7 @@ TEST_F(FormatTest, AlignConsecutiveAssignments) {
"y = 1;",
Alignment);
- EXPECT_EQ(Alignment.ReflowComments, true);
+ EXPECT_EQ(Alignment.ReflowComments, FormatStyle::RCS_Always);
Alignment.ColumnLimit = 50;
verifyFormat("int x = 0;\n"
"int yy = 1; /// specificlennospace\n"
diff --git a/clang/unittests/Format/FormatTestComments.cpp b/clang/unittests/Format/FormatTestComments.cpp
index 4eea14282c3256..5eefd767706a3e 100644
--- a/clang/unittests/Format/FormatTestComments.cpp
+++ b/clang/unittests/Format/FormatTestComments.cpp
@@ -520,9 +520,36 @@ TEST_F(FormatTestComments, AlignsBlockComments) {
TEST_F(FormatTestComments, CommentReflowingCanBeTurnedOff) {
FormatStyle Style = getLLVMStyleWithColumns(20);
- Style.ReflowComments = false;
+ Style.ReflowComments = FormatStyle::RCS_Never;
verifyFormat("// aaaaaaaaa aaaaaaaaaa aaaaaaaaaa", Style);
verifyFormat("/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa */", Style);
+ verifyNoChange("/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa\n"
+ "aaaaaaaaa*/",
+ Style);
+ verifyNoChange("/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa\n"
+ " aaaaaaaaa*/",
+ Style);
+ verifyNoChange("/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa\n"
+ " * aaaaaaaaa*/",
+ Style);
+}
+
+TEST_F(FormatTestComments, CommentReflowingCanApplyOnlyToIndents) {
+ FormatStyle Style = getLLVMStyleWithColumns(20);
+ Style.ReflowComments = FormatStyle::RCS_IndentOnly;
+ verifyFormat("// aaaaaaaaa aaaaaaaaaa aaaaaaaaaa", Style);
+ verifyFormat("/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa */", Style);
+ verifyNoChange("/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa\n"
+ "aaaaaaaaa*/",
+ Style);
+ verifyNoChange("/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa\n"
+ " aaaaaaaaa*/",
+ Style);
+ verifyFormat("/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa\n"
+ " * aaaaaaaaa*/",
+ "/* aaaaaaaaa aaaaaaaaaa aaaaaaaaaa\n"
+ " * aaaaaaaaa*/",
+ Style);
}
TEST_F(FormatTestComments, CorrectlyHandlesLengthOfBlockComments) {
More information about the cfe-commits
mailing list