[clang-format] Adds a formatter for aligning trailing comments over empty lines

[yusuke-kadowaki]

Summary

This patch addresses https://github.com/llvm/llvm-project/issues/19756

[HazardyKnusperkeks]

clang/include/clang/Format/Format.h

448

Maybe you can port this to AlignConsecutiveStyle? AcrossComments would not affect anything in this context.

450

Documentation is missing.

clang/lib/Format/Format.cpp

1510

Not needed since it inherits everything from LLVMStyle.
Same for the other styles.

clang/lib/Format/WhitespaceManager.cpp

948

Just make it clear for everyone, so one would not need to guess, when trying to understand the code.

[MyDeveloperDay]

clang/lib/Format/Format.cpp

1659

ditto remove

clang/unittests/Format/FormatTest.cpp

25894

I think it needs more tests than just include examples

[yusuke-kadowaki]

• Port AlignTrailingComments to one of the members of AlignConsecutiveStyle
• Add documentation
• Move tests to FormatTestComments
• Add more tests
  • I left some failing tests that I think we should add implementations to make them pass. That's because I wanted to get some reviews for the work I've done so far before tackling on it.

[yusuke-kadowaki]

clang/include/clang/Format/Format.h

448

I took this approach

clang/unittests/Format/FormatTest.cpp

74–77

Sorry I will remove these next time I update this patch.

[HazardyKnusperkeks]

Please mark things as done.

clang/include/clang/Format/Format.h

297

Run clang/docs/tools/dump_format_style.py.

306

16

I'm pretty sure we don't need longer than that. :)

But mention that it existed as AlignTrailingComments since 3.7. There should be examples for that in this file.

448

Take a look at D127578.

clang/lib/Format/Format.cpp

685

Please sort.

[yusuke-kadowaki]

• Remove my comments
• Update documentation
• Sort

[MyDeveloperDay]

clang/lib/Format/Format.cpp

658

you can't remove an option, otherwise you'll break everyones .clang-format

[MyDeveloperDay]

clang/unittests/Format/FormatTest.cpp

20314

don't remove

[HazardyKnusperkeks]

clang/lib/Format/Format.cpp

658

That's not correct. We have done it:
D108752 -> D108882 -> D127390

You can remove (and in this case should), but you still need to parse it and act accordingly. Which is done as far as I can see.

clang/unittests/Format/FormatTest.cpp

20314

It's tested below.

[MyDeveloperDay]

clang/lib/Format/Format.cpp

658

sorry thats what I meant, you can remove it, but you have to make it turn on the correct new style that keeps exactly the old user case, and you can't remove it from the configuration parsing otherwise anyone who has it in their .clang-format is immediately broken with an unknown option.

to be honest this is an annoyance for introducing new features, which at some point I'd like to drop, you can't have a new option which is not read

For me, when we introduced new languages, or new features like InsertBraces etc.. I want to put it in my .clang-format even though other people they aren't using a version that uses it. (becuase it won't impact them), i.e. it won't add braces or correct QualifierOrder that doesn't bother me

[MyDeveloperDay]

clang/docs/ClangFormatStyleOptions.rst

797

why do we need Enabled?

isn't it just

false:
AcrossEmptyLines: false
AcrossComments: false

true:
AcrossEmptyLines: true
AcrossComments: true

[HazardyKnusperkeks]

clang/docs/ClangFormatStyleOptions.rst

797

The struct is a bit older. And we need Enabled, one might wish to align only really consecutive comments, as the option right now does. (Same for macros, assignments, etc..)

clang/lib/Format/Format.cpp

658

Do you disagree that it actually is parsed?

But that compatibility parsing has nothing to do with ignoring unknown (new) options.

[MyDeveloperDay]

clang/docs/ClangFormatStyleOptions.rst

785

may be AcrossEmptyLines should be a number (to mean the number of empty lines)

794

Should this say AlignedConsecutuveCommets

797

I'm still not sure I understand, plus are those use cases you describe tested, I couldn't see that.

If feels like what you are saying is that AlignConsecutiveStyle is used elsewhere and it has options that don't pertain to aligning comments?

I couldn't tell if feel like this documentation is describing something other than AligningTrailingComments, if I'm confused users could be too?

clang/unittests/Format/FormatTestComments.cpp

2876

can we have real comments with different lengths?

[yusuke-kadowaki]

• Fix the newline condition
• Update tests

[yusuke-kadowaki]

clang/docs/ClangFormatStyleOptions.rst

785

We need to introduce a new struct to do that since AlignConsecutiveStyle is shared with some options and not possible to be changed. Plus I think more than two empty lines are formatted to one empty line anyway.

794

No. This part is a documentation about AlignConsecutiveStyle type, which is appended automatically after all the options that take AlignConsecutiveStyle type.

797

As for the Enabled option,
Enabled: true
AcrossEmptyLines: false

is supposed to work in the same way as the old style AlignTrailingComments. So the tests of AlignTrailingComments are the test cases.

For the documentation, I also thought it was a bit confusing when I first saw it because the description of the option and the style is kind of connected. But as I also mentioned above, this part is automatically append and it affects all the other options that have AlignConsecutiveStyle if we change. So I think it should be another patch even if we are to modify it.

clang/lib/Format/Format.cpp

658

I confirmed the old style AlignTrailingComments works and it's also tested with CHECK_PARSE if I understand correctly.

[HazardyKnusperkeks]

clang/docs/ClangFormatStyleOptions.rst

785

There MaxEmptyLinesToKeep which would allow to set it higher.

If we want to change the bool to an unsigned, then that should be a different change.

794

Which we could change to reflect that it's used for multiple options.

797

I'm still not sure I understand, plus are those use cases you describe tested, I couldn't see that.

If feels like what you are saying is that AlignConsecutiveStyle is used elsewhere and it has options that don't pertain to aligning comments?

I couldn't tell if feel like this documentation is describing something other than AligningTrailingComments, if I'm confused users could be too?

It was added in D93986 as an enum, and in D119599 made into a struct which then had 2 options only valid for assignments, not the macros or declarations. Both accepted by you.

So I see no problem, but think it is the right thing, to port aligning comments to the struct, even if the flag AccrossComments is a noop in this case. When this lands I actually plan to add a flag only used by comments.

clang/unittests/Format/FormatTestComments.cpp

2863

Interesting would be a comment which is split, do we continue to align, or not?

2958

Trailing whitespace.

[yusuke-kadowaki]

• Remove trailing whitespace
• Update document

[yusuke-kadowaki]

clang/docs/ClangFormatStyleOptions.rst

785

Oh I didn't know MaxEmptyLinesToKeep. Thank you for sharing.
I can try to change it that way when we done with this patch. Test cases would be complicated tho.

clang/unittests/Format/FormatTestComments.cpp

2863

Could you give me a specific example?

[HazardyKnusperkeks]

clang/include/clang/Format/Format.h

143

That I wouldn't change.

153

The change/addition has to be here, since here it directly states AlignConsecutiveMacros.

clang/unittests/Format/FormatTestComments.cpp

2863

Something like

int foo = 2323234; // Comment
int bar = 52323;   // This is a very long comment, ...
                   // which is wrapped around.

int x = 2; // Is this still aligned?

You may need to make the comment longer or reduce the column limit, as often used for testing the wrapping behavior.

[yusuke-kadowaki]

• Update tests
• Fix document

[yusuke-kadowaki]

clang/include/clang/Format/Format.h

143

reverted

153

What are you meaning to say here? I thought saying AlignConsecutiveStyle is used for multiple options is what we are trying to do.

Should we say something like,

Here AlignConsecutiveMacros is used as an example, but in practice AlignConsecutiveStyle is also used with other options.

in this place?

clang/unittests/Format/FormatTestComments.cpp

2863

Added that case with some column limits. I think it's working as expected. What do you think?

[HazardyKnusperkeks]

In my opinion we are nearly done.

clang/docs/ClangFormatStyleOptions.rst

3658

Anyone knows where this comes from?
You are using the script to generate the rst, right?

clang/include/clang/Format/Format.h

153

The example mentions explicitly only AlignConsecutiveMacros which is a bit misleading if you are only looking at the documentation of AlignConsecutiveAssignments for example.

This is not your fault, and I'm fine with ignoring it here. A separate patch to fix that is welcome. :)

clang/lib/Format/WhitespaceManager.cpp

948

And accompanied by a short test. That should be everything to support the mixture of the options, right?

1020

Is this clang-format formatted?

clang/unittests/Format/FormatTestComments.cpp

4319

Please revert this.

[MyDeveloperDay]

Is there a technical reason for reusing the struct rather than introducing a new one?

[HazardyKnusperkeks]

In D132131#3766590, @MyDeveloperDay wrote:

Is there a technical reason for reusing the struct rather than introducing a new one?

I see, good point. Really only if one would port the implementation to AlignTokens. If that's feasible (or sensible) I don't know. Otherwise one will only reuse the parsing code.

[yusuke-kadowaki]

• Revert doc
• Revert rst as well
• Apply format
• Update implementation to deal with the setting of MaxEmptyLinesToKeep
• Add test for the combination with MaxEmptyLinesToKeep

clang/docs/ClangFormatStyleOptions.rst

3658

Yes, I'm using dump_format_style.py.

clang/include/clang/Format/Format.h

153

Got it. Reverted for now.

clang/lib/Format/WhitespaceManager.cpp

948

That should be everything to support the mixture of the options, right?

I think so.

Done.

1020

I forgot that. Also formatted some other diffs.

clang/unittests/Format/FormatTestComments.cpp

4319

Reverted.

[MyDeveloperDay]

I feel this patch leave the documentation in a right state, I won’t be giving it an accept in this form. Please also mark the comments as done once addressed so we know you’ve read and fixed our requests

clang/docs/ClangFormatStyleOptions.rst

823

I’m sorry I just don’t think this documentation is now correct, all because you are trying I believe to reuse a structure that has options that’s not needed,

clang/include/clang/Format/Format.h

298

Isn’t this completely wrong?

446

And this

[MyDeveloperDay]

clang/docs/ClangFormatStyleOptions.rst

794

Or you could use your own struct! And it would be correct and not full of options that don’t apply.

[yusuke-kadowaki]

Can we all agree with the decision whether we use the AlignConsecutiveStyle or introduce a new struct before I start implementing or updating the document?
IMO, both are reasonable in some respects so I'd like you owners to decide.

Please also mark the comments as done once addressed so we know you’ve read and fixed our requests

I'm reading all the comments but leaving some comments not done on purpose that I think the discussion is not done. Isn't it a right thing to do here?

clang/include/clang/Format/Format.h

298

Could you please be more specific about why you think so when pointing out something? I don't see why you think it's wrong. I also would like to mention that I followed @HazardyKnusperkeks's request on this.

[MyDeveloperDay]

My personal preference is a new struct without Enabled

clang/lib/Format/Format.cpp

1247

Won’t you need to initialise the members here as above

clang/unittests/Format/FormatTestComments.cpp

2908

Any reason why these are not verifyformats.

[MyDeveloperDay]

clang/include/clang/Format/Format.h

298

Ignore my comment

446

Ignore this comment

[yusuke-kadowaki]

• Change to use verifyFormat

clang/lib/Format/Format.cpp

1247

Members are false when initialized so I don't know why those above are initialized explicitly as false.

[MyDeveloperDay]

clang/unittests/Format/FormatTestComments.cpp

2930

Why not verifyFormat here too and below?

[HazardyKnusperkeks]

In D132131#3770170, @MyDeveloperDay wrote:

My personal preference is a new struct without Enabled

We go for a new struct. But why without enabled?
Currently we have a boolean on/off switch AlignTrailingComments. This change wanted to add a second boolean to enable aligning ignoring empty lines, naturally its value only matters if AlignTrailingComments is true.
My request was to use the existing struct (and I'm still in favor of that, but not strong enough to fight anything or anybody over it), but a struct seems to be better than 2 booleans. But an on/off switch still needs to be there, and at least using the same name as other options Enabled seems to be the most consistent solution.

[MyDeveloperDay]

In D132131#3771005, @HazardyKnusperkeks wrote:

In D132131#3770170, @MyDeveloperDay wrote:

My personal preference is a new struct without Enabled

We go for a new struct. But why without enabled?
Currently we have a boolean on/off switch AlignTrailingComments. This change wanted to add a second boolean to enable aligning ignoring empty lines, naturally its value only matters if AlignTrailingComments is true.
My request was to use the existing struct (and I'm still in favor of that, but not strong enough to fight anything or anybody over it), but a struct seems to be better than 2 booleans. But an on/off switch still needs to be there, and at least using the same name as other options Enabled seems to be the most consistent solution.

We don’t normally use Enabled for other structs, maybe we don’t use bool but enums (Always, Never, Leave)

[yusuke-kadowaki]

• Introduce new struct
• Update document

This change should be ok for everyone (I hope). BTW, please correct my English if any or create a whole new one for me since I'm not so sure what I wrote delivers well.

[yusuke-kadowaki]

clang/unittests/Format/FormatTestComments.cpp

2930

To test the ColumnLimit behavior.

[MyDeveloperDay]

clang/unittests/Format/FormatTestComments.cpp

2930

pretty sure you can pass in a style

[MyDeveloperDay]

clang/docs/ClangFormatStyleOptions.rst

931

Is Don'tAlign the same as Leave that other options support (for options it best if we try and use the same terminiology

Always,Never,Leave (if that fits)

clang/include/clang/Format/Format.h

373

all options have a life cycle

bool -> enum -> struct

One of the thing I ask you before, would we want to align across N empty lines, if ever so they I think
we should go straight to a struct

[yusuke-kadowaki]

clang/docs/ClangFormatStyleOptions.rst

931

IMHO, Leave probably fits but DontAlign is more straightforward. Also DontAlign is used for other alignment styles like BracketAlignmentStyle so it would be more natural.

clang/include/clang/Format/Format.h

373

all options have a life cycle

I see your point. But we are checking Style.MaxEmptyLinesToKeep to determine how many consecutive lines to align. So currently no need to specify it from the option. You'll find the implementation below.

clang/unittests/Format/FormatTestComments.cpp

2930

Style isn't a problem here. But when testing column limit, you want to see before and after the line split into multiple lines. Original test cases of AlignTrailingComments also use this EXPECT_EQ style not verifyFormat.

[MyDeveloperDay]

clang/docs/ClangFormatStyleOptions.rst

931

Leave should mean do nothing.. I'm personally not a fan of DontAlign because obvious there should be a ' between the n and the t but I see we use it elsewhere

But actually now I see your DontAlign is effectively the as before (i.e. it will not add extra spaces)

The point of Leave is what people have been asking for when we introduce a new option, that is we if possible add an option which means "Don't touch it at all" i.e. if I want to have

int a;           //  abc
int b;   /// bcd
int c;                                    // cde

Then so be it

clang/include/clang/Format/Format.h

373

I think its a bad idea to hijack a different option to do this..I don't think it means the same thing and I think what whilst it might work there will be someone somewhere who doesn't want it to behave like this and will call it out as a bug.

[HazardyKnusperkeks]

clang/docs/ClangFormatStyleOptions.rst

931

Leave is a nice option, yes.
I think it is complementary to Dont.

But maybe if the option is called AlignTrailingComments one may interpret Leave not as "don't touch the position of a comment at all" (what do we do, if the comment is outside of the column limit?), but as "just don't touch them, when they are somewhat aligned". Just a thought.

clang/include/clang/Format/Format.h

373

Since you are strictly against Enabled what to put into a struct?

[MyDeveloperDay]

an example of the exact reason why we should not reuse the same struct... https://github.com/llvm/llvm-project/issues/57464

[MyDeveloperDay]

another reason for using a struct, is that we might want to say something like "AlignNamespaceTrainingComments:false" https://github.com/llvm/llvm-project/issues/57504

[yusuke-kadowaki]

clang/docs/ClangFormatStyleOptions.rst

931

Leave should mean do nothing

Ok now I see what Leave means.
But that should be another piece of work no?

Of course me or someone can add the feature later (I don't really know how to implement that though at least for now)

clang/include/clang/Format/Format.h

373

Since you are strictly against Enabled what to put into a struct?

@MyDeveloperDay
Can you answer this? Plus it would be helpful if you just write down what your ideal struct be like.

I don't think it means the same thing

How so? There's no empty lines more than MaxEmptyLinesToKeep all the time no?

[HazardyKnusperkeks]

In D132131#3776956, @MyDeveloperDay wrote:

an example of the exact reason why we should not reuse the same struct... https://github.com/llvm/llvm-project/issues/57464

Just a bit rephrasing.

In D132131#3777004, @MyDeveloperDay wrote:

another reason for using a struct, is that we might want to say something like "AlignNamespaceTrainingComments:false" https://github.com/llvm/llvm-project/issues/57504

Something like that we really want, and that is something I'd like to put on top of this change. Also for all comments following a }. That's the only reason I've disabled aligning comments for now.

clang/docs/ClangFormatStyleOptions.rst

931

Fine by me.

clang/include/clang/Format/Format.h

373

I don't think it means the same thing

How so? There's no empty lines more than MaxEmptyLinesToKeep all the time no?

But you could set MaxEmptyLinesToKeep to 3 and aligning comments to over 2 empty lines.

int thisIsAVariable = 5; // It Really is


int stillAligned = 2;    // Yep



int notSoMuch = 2; // Nope

It certainly doesn't hurt to have a value there.

373

Since you are strictly against Enabled what to put into a struct?

@MyDeveloperDay
Can you answer this? Plus it would be helpful if you just write down what your ideal struct be like.

For me it would currently look like:

struct Style {
  enum E {
    Yes,
    No,
  };
  E State;
  unsigned OverEmptyLines;
}

Names are open for debate.

[MyDeveloperDay]

struct Style {
  enum E {
    Yes,
    No,
  };
  unsigned OverEmptyLines;
}

I don't understand the need for state as a struct could have multiple options (as enums) each enum should have a state that means "Leave"

[MyDeveloperDay]

But you could set MaxEmptyLinesToKeep to 3 and aligning comments to over 2 empty lines.

Correct! lets assume MaxEmptyLinesToKeep = 3

if this case is valid in that case

int a;            // Foo
int longer foo;   // Foo
int verylong foo; // Foo

then so is this

int a;            // Foo

int longer foo;   // Foo

int verylong foo; // Foo

and so is this...

int a;            // Foo


int longer foo;   // Foo


int verylong foo; // Foo

but not this

int a;          // Foo

int longer foo; // Foo


 
int verylong foo; // Foo

Regardless of how many lines I am willing or not willing to keep, I know it feels orthogonal, but its actually independent (so don't use it as my setting), or you could manipulate code in a way I don't want changed (and they people will complain)

Its one of those cases there it feels like they can be the same, but the answer is should they? or are we making an assumption about what people want rather than giving them the control.

I agree if OverEmptyLines > MaxEmptyLinesToKeep then it feels kinda odd (but what about lines that are // clang-format off'd should we count those?

[yusuke-kadowaki]

Just updated the Style struct field definitions for review. Haven't implemented the logics.

[yusuke-kadowaki]

Thank you for the detailed explanation. I understood the needs for unsigned OverEmptyLines field.
Please review the struct definition first. Then I'll implement the rest of the code.

clang/include/clang/Format/Format.h

428–433

I don't understand the need for state as a struct could have multiple options (as enums) each enum should have a state that means "Leave"

@MyDeveloperDay
Without having state, how can this be implemented?

[MyDeveloperDay]

clang/include/clang/Format/Format.h

406

Kind? doesn't feel like the right word

428–433

bool Enabled = (Kind != FormatStyle::TCAS_Leave)

[yusuke-kadowaki]

So other than the naming, does the struct look good?

clang/include/clang/Format/Format.h

406

What do you recommend?

428–433

Oh ok so I think we are on the same page.

[MyDeveloperDay]

clang/include/clang/Format/Format.h

428

do you need this?

[yusuke-kadowaki]

Implementation done except for the Leave option.

clang/include/clang/Format/Format.h

428

Yes. Without this it does not compile.

[yusuke-kadowaki]

clang/docs/ClangFormatStyleOptions.rst

931

@HazardyKnusperkeks
Is this complicated? If it's not I might as well do this.

Also it would be helpful if you could provide some implementation guidance. Sorry to ask this even though I haven't tried it myself yet.

[HazardyKnusperkeks]

clang/docs/ClangFormatStyleOptions.rst

931

@HazardyKnusperkeks
Is this complicated? If it's not I might as well do this.

Also it would be helpful if you could provide some implementation guidance. Sorry to ask this even though I haven't tried it myself yet.

I think you refer to the non aligning of comments following r_braces. I don't think so, because at least the cases I think about the r_brace should be the first token on a unwrapped line, so you just have to check for Line->First.

[yusuke-kadowaki]

Implment trailing comments Leave option

There is two options, I think, when leaving comments exceeds the column limit.

1. Just format the trailing comments
2. Ignore the column limit for that line.

This implementation does the first option because ignoring column limit semms too much for just taking care of trailing comments.

[yusuke-kadowaki]

clang/docs/ClangFormatStyleOptions.rst

931

Isn't this for https://github.com/llvm/llvm-project/issues/57504?
I thought that's different than leaving all the trailing comments.

[HazardyKnusperkeks]

clang/lib/Format/WhitespaceManager.cpp

967–969

Elide the braces.

clang/unittests/Format/FormatTestComments.cpp

3045

Can you do that in reverse order (more spaces at top) also?

[yusuke-kadowaki]

Added more tests
Removed braces

[HazardyKnusperkeks]

For me this is good. But please wait for @MyDeveloperDay .

clang/lib/Format/WhitespaceManager.cpp

949–951

These braces also.

[MyDeveloperDay]

Can you mark your comments done, I think you missed removing some braces that @HazardyKnusperkeks asked you to remove

[MyDeveloperDay]

I think you also need to rebase to get rid of the "ClangFormatStyleOptions.rst" (which means you need to rebase and rerun dump_format_style.py

[yusuke-kadowaki]

• Rebased
• Remove more braces
• Update rst

[yusuke-kadowaki]

Thank you for all the reviews. Appreciate it.

So will some of you land this or am I supposed to do something else?

[rymiel]

Please provide a name and an email so someone could commit it on your behalf

[yusuke-kadowaki]

In D132131#3865004, @rymiel wrote:

Please provide a name and an email so someone could commit it on your behalf

name: Yusuke Kadowaki
email: [e-mail]

[yusuke-kadowaki]

@MyDeveloperDay @HazardyKnusperkeks

Could you land this please if we are not waiting for anything?

clang/docs/ClangFormatStyleOptions.rst

.. code-block:: c++
         int b; \
         int dddddddddd;
 
   * ``ENAS_Left`` (in configuration: ``Left``)
     Align escaped newlines as far left as possible.
 
     .. code-block:: c++
 
       true:
       #define A   \
         int aaaa; \
         int b;    \
         int dddddddddd;
 
       false:
 
   * ``ENAS_Right`` (in configuration: ``Right``)
     Align escaped newlines in the right-most column.
 
     .. code-block:: c++
 
       #define A                                                                      \
         int aaaa;                                                                    \
         int b;                                                                       \
         int dddddddddd;
 
 
 
 **AlignOperands** (``OperandAlignmentStyle``) :versionbadge:`clang-format 3.5`
**AlignOperands** (``OperandAlignmentStyle``) :versionbadge:`clang-format 3.5`
 
   * ``OAS_Align`` (in configuration: ``Align``)
     Horizontally align operands of binary and ternary expressions.
 
     Specifically, this aligns operands of a single expression that needs
     to be split over multiple lines, e.g.:
 
     .. code-block:: c++
 
       int aaa = bbbbbbbbbbbbbbb +
                 ccccccccccccccc;
 
     When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is
     aligned with the operand on the first line.
 
     .. code-block:: c++
 
* ``OAS_AlignAfterOperator`` (in configuration: ``AlignAfterOperator``)
 
     .. code-block:: c++
 
       int aaa = bbbbbbbbbbbbbbb
               + ccccccccccccccc;
 
 
 
-**AlignTrailingComments** (``Boolean``) :versionbadge:`clang-format 3.7`
-  If ``true``, aligns trailing comments.
+**AlignTrailingComments** (``TrailingCommentsAlignmentStyle``) :versionbadge:`clang-format 3.7`
+  Control of trailing comments.
+
+  NOTE: As of clang-format 16 this option is not a bool but can be set
+  to the options. Conventional bool options still can be parsed as before.
+
+
+  .. code-block:: yaml
+
+    # Example of usage:
+    AlignTrailingComments:
+      Kind: Always
+      OverEmptyLines: 2
+
+  Nested configuration flags:
+
+  Alignment options
+
+  * ``TrailingCommentsAlignmentKinds Kind``
+    Specifies the way to align trailing comments
+
+    Possible values:
+
+    * ``TCAS_Leave`` (in configuration: ``Leave``)
+      Leave trailing comments as they are.
 
       .. code-block:: c++
 
-    true:                                   false:
-    int a;     // My comment a      vs.     int a; // My comment a
-    int b = 2; // comment  b                int b = 2; // comment about b
+        int a;    // comment
+        int ab;       // comment
+
+        int abc;  // comment
+        int abcd;     // comment
+
+    * ``TCAS_Always`` (in configuration: ``Always``)
+      Align trailing comments.
+
+      .. code-block:: c++
+
+        int a;  // comment
+        int ab; // comment
+
+        int abc;  // comment
+        int abcd; // comment
+
+    * ``TCAS_Never`` (in configuration: ``Never``)
+      Don't align trailing comments but other formatter applies.
+
+      .. code-block:: c++
+
+        int a; // comment
+        int ab; // comment
+
+        int abc; // comment
+        int abcd; // comment
+
+
+  * ``unsigned OverEmptyLines`` How many empty lines to apply alignment
+    With ``MaxEmptyLinesToKeep`` is 2 and ``OverEmptyLines`` is 2,
+
+    .. code-block:: c++
+
+      int a;      // all these
+
+      int ab;     // comments are
+
+
+      int abcdef; // aligned
+    And with ``MaxEmptyLinesToKeep`` is 2 and ``OverEmptyLines`` is 1,
+
+    .. code-block:: c++
+
+      int a;  // these are
+
+      int ab; // aligned
+
+
+      int abcdef; // but this isn't
+
 
 **AllowAllArgumentsOnNextLine** (``Boolean``) :versionbadge:`clang-format 9`
   If a function call or braced initializer list doesn't fit on a
   line, allow putting all arguments onto the next line, even if
   ``BinPackArguments`` is ``false``.
 
   .. code-block:: c++
 
     true:
     callFunction(
         a, b, c, d);
 
.. code-block:: c++
        int const *a;
 
   * ``QAS_Custom`` (in configuration: ``Custom``)
     Change specifiers/qualifiers to be aligned based on ``QualifierOrder``.
     With:
 
     .. code-block:: yaml
 
       QualifierOrder: ['inline', 'static', 'type', 'const']
 
 
     .. code-block:: c++
 
 
        int const a;
        int const *a;
 

clang/include/clang/Format/Format.h

struct FormatStyle {
   /// NOTE: As of clang-format 15 this option only applied to arrays with equal
   /// number of columns per row.
   ///
   /// \version 13
   ArrayInitializerAlignmentStyle AlignArrayOfStructures;
 
   /// Alignment options.
   ///
   /// They can also be read as a whole for compatibility. The choices are:
   /// - None
   /// - Consecutive
   /// - AcrossEmptyLines
   /// - AcrossComments
   /// - AcrossEmptyLinesAndComments
   ///
   /// For example, to align across empty lines and not across comments, either
   /// of these work.
   /// \code
   ///   AlignConsecutiveMacros: AcrossEmptyLines
   ///
   ///   AlignConsecutiveMacros:
   ///     Enabled: true
   ///     AcrossEmptyLines: true
   ///     AcrossComments: false
   /// \endcode
   struct AlignConsecutiveStyle {
     /// Whether aligning is enabled.
struct FormatStyle {
   /// This will result in formattings like:
   /// \code
   ///   int         aaaa = 12;
   ///   float       b = 23;
   ///   std::string ccc;
   /// \endcode
   /// \version 3.8
   AlignConsecutiveStyle AlignConsecutiveDeclarations;
 
   /// Different styles for aligning escaped newlines.
   enum EscapedNewlineAlignmentStyle : int8_t {
     /// Don't align escaped newlines.
     /// \code
     ///   #define A \
     ///     int aaaa; \
     ///     int b; \
     ///     int dddddddddd;
     /// \endcode
     ENAS_DontAlign,
     /// Align escaped newlines as far left as possible.
     /// \code
     ///   true:
     ///   #define A   \
     ///     int aaaa; \
     ///     int b;    \
     ///     int dddddddddd;
enum OperandAlignmentStyle : int8_t {
     OAS_AlignAfterOperator,
   };
 
   /// If ``true``, horizontally align operands of binary and ternary
   /// expressions.
   /// \version 3.5
   OperandAlignmentStyle AlignOperands;
 
-  /// If ``true``, aligns trailing comments.
+  /// Enums for AlignTrailingComments
+  enum TrailingCommentsAlignmentKinds : int8_t {
+    /// Leave trailing comments as they are.
     /// \code
-  ///   true:                                   false:
-  ///   int a;     // My comment a      vs.     int a; // My comment a
-  ///   int b = 2; // comment  b                int b = 2; // comment about b
+    ///   int a;    // comment
+    ///   int ab;       // comment
+    ///
+    ///   int abc;  // comment
+    ///   int abcd;     // comment
+    /// \endcode
+    TCAS_Leave,
+    /// Align trailing comments.
+    /// \code
+    ///   int a;  // comment
+    ///   int ab; // comment
+    ///
+    ///   int abc;  // comment
+    ///   int abcd; // comment
+    /// \endcode
+    TCAS_Always,
+    /// Don't align trailing comments but other formatter applies.
+    /// \code
+    ///   int a; // comment
+    ///   int ab; // comment
+    ///
+    ///   int abc; // comment
+    ///   int abcd; // comment
+    /// \endcode
+    TCAS_Never,
+  };
+
+  /// Alignment options
+  struct TrailingCommentsAlignmentStyle {
+    /// Specifies the way to align trailing comments
+    TrailingCommentsAlignmentKinds Kind;
+    /// How many empty lines to apply alignment
+    /// With ``MaxEmptyLinesToKeep`` is 2 and ``OverEmptyLines`` is 2,
+    /// \code
+    ///   int a;      // all these
+    ///
+    ///   int ab;     // comments are
+    ///
+    ///
+    ///   int abcdef; // aligned
+    /// \endcode
+    /// And with ``MaxEmptyLinesToKeep`` is 2 and ``OverEmptyLines`` is 1,
+    /// \code
+    ///   int a;  // these are
+    ///
+    ///   int ab; // aligned
+    ///
+    ///
+    ///   int abcdef; // but this isn't
+    /// \endcode
+    unsigned OverEmptyLines;
+
+    bool operator==(const TrailingCommentsAlignmentStyle &R) const {
+      return Kind == R.Kind && OverEmptyLines == R.OverEmptyLines;
+    }
+    bool operator!=(const TrailingCommentsAlignmentStyle &R) const {
+      return !(*this == R);
+    }
+  };
+
+  /// Control of trailing comments.
+  ///
+  /// NOTE: As of clang-format 16 this option is not a bool but can be set
+  /// to the options. Conventional bool options still can be parsed as before.
+  ///
+  /// \code{.yaml}
+  ///   # Example of usage:
+  ///   AlignTrailingComments:
+  ///     Kind: Always
+  ///     OverEmptyLines: 2
   /// \endcode
   /// \version 3.7
-  bool AlignTrailingComments;
+  TrailingCommentsAlignmentStyle AlignTrailingComments;
 
   /// \brief If a function call or braced initializer list doesn't fit on a
   /// line, allow putting all arguments onto the next line, even if
   /// ``BinPackArguments`` is ``false``.
   /// \code
   ///   true:
   ///   callFunction(
   ///       a, b, c, d);
   ///
   ///   false:

clang/lib/Format/Format.cpp

static void mapping(IO &IO, FormatStyle::AlignConsecutiveStyle &Value) {
     IO.mapOptional("AcrossEmptyLines", Value.AcrossEmptyLines);
     IO.mapOptional("AcrossComments", Value.AcrossComments);
     IO.mapOptional("AlignCompound", Value.AlignCompound);
     IO.mapOptional("PadOperators", Value.PadOperators);
   }
 };
 
 template <>
+struct ScalarEnumerationTraits<FormatStyle::TrailingCommentsAlignmentKinds> {
+  static void enumeration(IO &IO,
+                          FormatStyle::TrailingCommentsAlignmentKinds &Value) {
+    IO.enumCase(Value, "Leave", FormatStyle::TCAS_Leave);
+    IO.enumCase(Value, "Always", FormatStyle::TCAS_Always);
+    IO.enumCase(Value, "Never", FormatStyle::TCAS_Never);
+  }
+};
+
+template <> struct MappingTraits<FormatStyle::TrailingCommentsAlignmentStyle> {
+  static void enumInput(IO &IO,
+                        FormatStyle::TrailingCommentsAlignmentStyle &Value) {
+    IO.enumCase(Value, "Leave",
+                FormatStyle::TrailingCommentsAlignmentStyle(
+                    {FormatStyle::TCAS_Leave, 1}));
+
+    IO.enumCase(Value, "Always",
+                FormatStyle::TrailingCommentsAlignmentStyle(
+                    {FormatStyle::TCAS_Always, 1}));
+
+    IO.enumCase(Value, "Never",
+                FormatStyle::TrailingCommentsAlignmentStyle(
+                    {FormatStyle::TCAS_Never, 1}));
+
+    // For backwards compatibility
+    IO.enumCase(Value, "true",
+                FormatStyle::TrailingCommentsAlignmentStyle(
+                    {FormatStyle::TCAS_Always, 1}));
+    IO.enumCase(Value, "false",
+                FormatStyle::TrailingCommentsAlignmentStyle(
+                    {FormatStyle::TCAS_Never, 1}));
+  }
+
+  static void mapping(IO &IO,
+                      FormatStyle::TrailingCommentsAlignmentStyle &Value) {
+    IO.mapOptional("Kind", Value.Kind);
+    IO.mapOptional("OverEmptyLines", Value.OverEmptyLines);
+  }
+};
+
+template <>
 struct ScalarEnumerationTraits<FormatStyle::ArrayInitializerAlignmentStyle> {
   static void enumeration(IO &IO,
                           FormatStyle::ArrayInitializerAlignmentStyle &Value) {
     IO.enumCase(Value, "None", FormatStyle::AIAS_None);
     IO.enumCase(Value, "Left", FormatStyle::AIAS_Left);
     IO.enumCase(Value, "Right", FormatStyle::AIAS_Right);
   }
 };
if (!IO.outputting()) {
       IO.mapOptional("AlignEscapedNewlinesLeft", Style.AlignEscapedNewlines);
       IO.mapOptional("DerivePointerBinding", Style.DerivePointerAlignment);
       IO.mapOptional("IndentFunctionDeclarationAfterType",
                      Style.IndentWrappedFunctionNames);
       IO.mapOptional("IndentRequires", Style.IndentRequiresClause);
       IO.mapOptional("PointerBindsToType", Style.PointerAlignment);
       IO.mapOptional("SpaceAfterControlStatementKeyword",
                      Style.SpaceBeforeParens);
     }
 
     IO.mapOptional("AccessModifierOffset", Style.AccessModifierOffset);
     IO.mapOptional("AlignAfterOpenBracket", Style.AlignAfterOpenBracket);
     IO.mapOptional("AlignArrayOfStructures", Style.AlignArrayOfStructures);
     IO.mapOptional("AlignConsecutiveAssignments",
                    Style.AlignConsecutiveAssignments);
     IO.mapOptional("AlignConsecutiveBitFields",
                    Style.AlignConsecutiveBitFields);
     IO.mapOptional("AlignConsecutiveDeclarations",
                    Style.AlignConsecutiveDeclarations);
     IO.mapOptional("AlignConsecutiveMacros", Style.AlignConsecutiveMacros);
     IO.mapOptional("AlignEscapedNewlines", Style.AlignEscapedNewlines);
     IO.mapOptional("AlignOperands", Style.AlignOperands);
     IO.mapOptional("AlignTrailingComments", Style.AlignTrailingComments);
     IO.mapOptional("AllowAllArgumentsOnNextLine",
                    Style.AllowAllArgumentsOnNextLine);
     IO.mapOptional("AllowAllParametersOfDeclarationOnNextLine",
                    Style.AllowAllParametersOfDeclarationOnNextLine);
     IO.mapOptional("AllowShortEnumsOnASingleLine",
                    Style.AllowShortEnumsOnASingleLine);
     IO.mapOptional("AllowShortBlocksOnASingleLine",
                    Style.AllowShortBlocksOnASingleLine);
FormatStyle getLLVMStyle(FormatStyle::LanguageKind Language) {
   FormatStyle LLVMStyle;
   LLVMStyle.InheritsParentConfig = false;
   LLVMStyle.Language = Language;
   LLVMStyle.AccessModifierOffset = -2;
   LLVMStyle.AlignEscapedNewlines = FormatStyle::ENAS_Right;
   LLVMStyle.AlignAfterOpenBracket = FormatStyle::BAS_Align;
   LLVMStyle.AlignArrayOfStructures = FormatStyle::AIAS_None;
   LLVMStyle.AlignOperands = FormatStyle::OAS_Align;
-  LLVMStyle.AlignTrailingComments = true;
   LLVMStyle.AlignConsecutiveAssignments = {};
   LLVMStyle.AlignConsecutiveAssignments.Enabled = false;
   LLVMStyle.AlignConsecutiveAssignments.AcrossEmptyLines = false;
   LLVMStyle.AlignConsecutiveAssignments.AcrossComments = false;
   LLVMStyle.AlignConsecutiveAssignments.AlignCompound = false;
   LLVMStyle.AlignConsecutiveAssignments.PadOperators = true;
   LLVMStyle.AlignConsecutiveBitFields = {};
   LLVMStyle.AlignConsecutiveDeclarations = {};
   LLVMStyle.AlignConsecutiveMacros = {};
+  LLVMStyle.AlignTrailingComments = {};
+  LLVMStyle.AlignTrailingComments.Kind = FormatStyle::TCAS_Always;
+  LLVMStyle.AlignTrailingComments.OverEmptyLines = 0;
   LLVMStyle.AllowAllArgumentsOnNextLine = true;
   LLVMStyle.AllowAllParametersOfDeclarationOnNextLine = true;
   LLVMStyle.AllowShortEnumsOnASingleLine = true;
   LLVMStyle.AllowShortFunctionsOnASingleLine = FormatStyle::SFS_All;
   LLVMStyle.AllowShortBlocksOnASingleLine = FormatStyle::SBS_Never;
   LLVMStyle.AllowShortCaseLabelsOnASingleLine = false;
   LLVMStyle.AllowShortIfStatementsOnASingleLine = FormatStyle::SIS_Never;
   LLVMStyle.AllowShortLambdasOnASingleLine = FormatStyle::SLS_All;
FormatStyle getGoogleStyle(FormatStyle::LanguageKind Language) {
   GoogleStyle.Standard = FormatStyle::LS_Auto;
 
   GoogleStyle.PenaltyReturnTypeOnItsOwnLine = 200;
   GoogleStyle.PenaltyBreakBeforeFirstCallParameter = 1;
 
   if (Language == FormatStyle::LK_Java) {
     GoogleStyle.AlignAfterOpenBracket = FormatStyle::BAS_DontAlign;
     GoogleStyle.AlignOperands = FormatStyle::OAS_DontAlign;
-    GoogleStyle.AlignTrailingComments = false;
+    GoogleStyle.AlignTrailingComments = {};
+    GoogleStyle.AlignTrailingComments.Kind = FormatStyle::TCAS_Never;
     GoogleStyle.AllowShortFunctionsOnASingleLine = FormatStyle::SFS_Empty;
     GoogleStyle.AllowShortIfStatementsOnASingleLine = FormatStyle::SIS_Never;
     GoogleStyle.AlwaysBreakBeforeMultilineStrings = false;
     GoogleStyle.BreakBeforeBinaryOperators = FormatStyle::BOS_NonAssignment;
     GoogleStyle.ColumnLimit = 100;
     GoogleStyle.SpaceAfterCStyleCast = true;
     GoogleStyle.SpacesBeforeTrailingComments = 1;
   } else if (Language == FormatStyle::LK_JavaScript) {
FormatStyle getMozillaStyle() {
   return MozillaStyle;
 }
 
 FormatStyle getWebKitStyle() {
   FormatStyle Style = getLLVMStyle();
   Style.AccessModifierOffset = -4;
   Style.AlignAfterOpenBracket = FormatStyle::BAS_DontAlign;
   Style.AlignOperands = FormatStyle::OAS_DontAlign;
-  Style.AlignTrailingComments = false;
+  Style.AlignTrailingComments = {};
+  Style.AlignTrailingComments.Kind = FormatStyle::TCAS_Never;
   Style.AllowShortBlocksOnASingleLine = FormatStyle::SBS_Empty;
   Style.BreakBeforeBinaryOperators = FormatStyle::BOS_All;
   Style.BreakBeforeBraces = FormatStyle::BS_WebKit;
   Style.BreakConstructorInitializers = FormatStyle::BCIS_BeforeComma;
   Style.Cpp11BracedListStyle = false;
   Style.ColumnLimit = 0;
   Style.FixNamespaceComments = false;
   Style.IndentWidth = 4;

clang/lib/Format/WhitespaceManager.cpp

 }
 
 void WhitespaceManager::alignTrailingComments() {
   unsigned MinColumn = 0;
   unsigned MaxColumn = UINT_MAX;
   unsigned StartOfSequence = 0;
   bool BreakBeforeNext = false;
   unsigned Newlines = 0;
+  unsigned int NewLineThreshold = 1;
+  if (Style.AlignTrailingComments.Kind == FormatStyle::TCAS_Always)
+    NewLineThreshold = Style.AlignTrailingComments.OverEmptyLines + 1;
+
   for (unsigned i = 0, e = Changes.size(); i != e; ++i) {
     if (Changes[i].StartOfBlockComment)
       continue;
     Newlines += Changes[i].NewlinesBefore;
     if (!Changes[i].IsTrailingComment)
       continue;
 
+    if (Style.AlignTrailingComments.Kind == FormatStyle::TCAS_Leave) {
+      auto OriginalSpaces =
+          Changes[i].OriginalWhitespaceRange.getEnd().getRawEncoding() -
+          Changes[i].OriginalWhitespaceRange.getBegin().getRawEncoding();
+      unsigned RestoredLineLength = Changes[i].StartOfTokenColumn +
+                                    Changes[i].TokenLength + OriginalSpaces;
+      // If leaving comments makes the line exceed the column limit, give up to
+      // leave the comments.
+      if (RestoredLineLength >= Style.ColumnLimit && Style.ColumnLimit != 0)
+        break;
+      Changes[i].Spaces = OriginalSpaces;
+      continue;
+    }
+
     unsigned ChangeMinColumn = Changes[i].StartOfTokenColumn;
     unsigned ChangeMaxColumn;
 
     if (Style.ColumnLimit == 0)
       ChangeMaxColumn = UINT_MAX;
     else if (Style.ColumnLimit >= Changes[i].TokenLength)
       ChangeMaxColumn = Style.ColumnLimit - Changes[i].TokenLength;
     else
       ChangeMaxColumn = ChangeMinColumn;
 
     // If we don't create a replacement for this change, we have to consider
     // it to be immovable.
     if (!Changes[i].CreateReplacement)
       ChangeMaxColumn = ChangeMinColumn;
 
     if (i + 1 != e && Changes[i + 1].ContinuesPPDirective)
       ChangeMaxColumn -= 2;
     // If this comment follows an } in column 0, it probably documents the
     // closing of a namespace and we don't want to align it.
     bool FollowsRBraceInColumn0 = i > 0 && Changes[i].NewlinesBefore == 0 &&
                                   Changes[i - 1].Tok->is(tok::r_brace) &&
                                   Changes[i - 1].StartOfTokenColumn == 0;
     bool WasAlignedWithStartOfNextLine = false;
-    if (Changes[i].NewlinesBefore == 1) { // A comment on its own line.
+    if (Changes[i].NewlinesBefore >= 1) { // A comment on its own line.
       unsigned CommentColumn = SourceMgr.getSpellingColumnNumber(
           Changes[i].OriginalWhitespaceRange.getEnd());
       for (unsigned j = i + 1; j != e; ++j) {
         if (Changes[j].Tok->is(tok::comment))
           continue;
 
         unsigned NextColumn = SourceMgr.getSpellingColumnNumber(
             Changes[j].OriginalWhitespaceRange.getEnd());
         // The start of the next token was previously aligned with the
         // start of this comment.
         WasAlignedWithStartOfNextLine =
             CommentColumn == NextColumn ||
             CommentColumn == NextColumn + Style.IndentWidth;
         break;
       }
     }
-    if (!Style.AlignTrailingComments || FollowsRBraceInColumn0) {
+    if (Style.AlignTrailingComments.Kind == FormatStyle::TCAS_Never ||
+        FollowsRBraceInColumn0) {
       alignTrailingComments(StartOfSequence, i, MinColumn);
       MinColumn = ChangeMinColumn;
       MaxColumn = ChangeMinColumn;
       StartOfSequence = i;
-    } else if (BreakBeforeNext || Newlines > 1 ||
+    } else if (BreakBeforeNext || Newlines > NewLineThreshold ||
                (ChangeMinColumn > MaxColumn || ChangeMaxColumn < MinColumn) ||
                // Break the comment sequence if the previous line did not end
                // in a trailing comment.
                (Changes[i].NewlinesBefore == 1 && i > 0 &&
                 !Changes[i - 1].IsTrailingComment) ||
                WasAlignedWithStartOfNextLine) {
       alignTrailingComments(StartOfSequence, i, MinColumn);
       MinColumn = ChangeMinColumn;
       MaxColumn = ChangeMaxColumn;

clang/unittests/Format/FormatTest.cpp

protected:
   }
 
   void _verifyFormat(const char *File, int Line, llvm::StringRef Expected,
                      llvm::StringRef Code,
                      const FormatStyle &Style = getLLVMStyle()) {
     ScopedTrace t(File, Line, ::testing::Message() << Code.str());
     EXPECT_EQ(Expected.str(), format(Expected, Style))
         << "Expected code is not stable";
     EXPECT_EQ(Expected.str(), format(Code, Style));
     if (Style.Language == FormatStyle::LK_Cpp) {
       // Objective-C++ is a superset of C++, so everything checked for C++
       // needs to be checked for Objective-C++ as well.
       FormatStyle ObjCStyle = Style;
       ObjCStyle.Language = FormatStyle::LK_ObjC;
       EXPECT_EQ(Expected.str(), format(test::messUp(Code), ObjCStyle));
     }
   }
 
   void _verifyFormat(const char *File, int Line, llvm::StringRef Code,
                      const FormatStyle &Style = getLLVMStyle()) {

 #define CHECK_PARSE_NESTED_BOOL(STRUCT, FIELD)                                 \
   CHECK_PARSE_NESTED_BOOL_FIELD(STRUCT, FIELD, #FIELD)
 
 #define CHECK_PARSE(TEXT, FIELD, VALUE)                                        \
   EXPECT_NE(VALUE, Style.FIELD) << "Initial value already the same!";          \
   EXPECT_EQ(0, parseConfiguration(TEXT, &Style).value());                      \
   EXPECT_EQ(VALUE, Style.FIELD) << "Unexpected value after parsing!"
 
+#define CHECK_PARSE_NESTED_VALUE(TEXT, STRUCT, FIELD, VALUE)                   \
+  EXPECT_NE(VALUE, Style.STRUCT.FIELD) << "Initial value already the same!";   \
+  EXPECT_EQ(0, parseConfiguration(#STRUCT ":\n  " TEXT, &Style).value());      \
+  EXPECT_EQ(VALUE, Style.STRUCT.FIELD) << "Unexpected value after parsing!";
+
 TEST_F(FormatTest, ParsesConfigurationBools) {
   FormatStyle Style = {};
   Style.Language = FormatStyle::LK_Cpp;
-  CHECK_PARSE_BOOL(AlignTrailingComments);
   CHECK_PARSE_BOOL(AllowAllArgumentsOnNextLine);
   CHECK_PARSE_BOOL(AllowAllParametersOfDeclarationOnNextLine);
   CHECK_PARSE_BOOL(AllowShortCaseLabelsOnASingleLine);
   CHECK_PARSE_BOOL(AllowShortEnumsOnASingleLine);
   CHECK_PARSE_BOOL(AllowShortLoopsOnASingleLine);
   CHECK_PARSE_BOOL(BinPackArguments);
   CHECK_PARSE_BOOL(BinPackParameters);
   CHECK_PARSE_BOOL(BreakAfterJavaFieldAnnotations);
#undef CHECK_ALIGN_CONSECUTIVE
   CHECK_PARSE("AlignOperands: Align", AlignOperands, FormatStyle::OAS_Align);
   CHECK_PARSE("AlignOperands: AlignAfterOperator", AlignOperands,
               FormatStyle::OAS_AlignAfterOperator);
   // For backward compatibility:
   CHECK_PARSE("AlignOperands: false", AlignOperands,
               FormatStyle::OAS_DontAlign);
   CHECK_PARSE("AlignOperands: true", AlignOperands, FormatStyle::OAS_Align);
 
+  CHECK_PARSE("AlignTrailingComments: Leave", AlignTrailingComments,
+              FormatStyle::TrailingCommentsAlignmentStyle(
+                  {FormatStyle::TCAS_Leave, 1}));
+  CHECK_PARSE("AlignTrailingComments: Always", AlignTrailingComments,
+              FormatStyle::TrailingCommentsAlignmentStyle(
+                  {FormatStyle::TCAS_Always, 1}));
+  CHECK_PARSE("AlignTrailingComments: Never", AlignTrailingComments,
+              FormatStyle::TrailingCommentsAlignmentStyle(
+                  {FormatStyle::TCAS_Never, 1}));
+  // For backwards compatibility
+  CHECK_PARSE("AlignTrailingComments: true", AlignTrailingComments,
+              FormatStyle::TrailingCommentsAlignmentStyle(
+                  {FormatStyle::TCAS_Always, 1}));
+  CHECK_PARSE("AlignTrailingComments: false", AlignTrailingComments,
+              FormatStyle::TrailingCommentsAlignmentStyle(
+                  {FormatStyle::TCAS_Never, 1}));
+  CHECK_PARSE_NESTED_VALUE("Kind: Always", AlignTrailingComments, Kind,
+                           FormatStyle::TCAS_Always);
+  CHECK_PARSE_NESTED_VALUE("Kind: Never", AlignTrailingComments, Kind,
+                           FormatStyle::TCAS_Never);
+  CHECK_PARSE_NESTED_VALUE("Kind: Leave", AlignTrailingComments, Kind,
+                           FormatStyle::TCAS_Leave);
+  CHECK_PARSE_NESTED_VALUE("OverEmptyLines: 1234", AlignTrailingComments,
+                           OverEmptyLines, 1234u);
+
   Style.UseTab = FormatStyle::UT_ForIndentation;
   CHECK_PARSE("UseTab: Never", UseTab, FormatStyle::UT_Never);
   CHECK_PARSE("UseTab: ForIndentation", UseTab, FormatStyle::UT_ForIndentation);
   CHECK_PARSE("UseTab: Always", UseTab, FormatStyle::UT_Always);
   CHECK_PARSE("UseTab: ForContinuationAndIndentation", UseTab,
               FormatStyle::UT_ForContinuationAndIndentation);
   CHECK_PARSE("UseTab: AlignWithSpaces", UseTab,
               FormatStyle::UT_AlignWithSpaces);

 
 TEST_F(FormatTest, RemoveSemicolon) {
   FormatStyle Style = getLLVMStyle();
   Style.RemoveSemicolon = true;
 
   verifyFormat("int max(int a, int b) { return a > b ? a : b; }",
                "int max(int a, int b) { return a > b ? a : b; };", Style);
 
   verifyFormat("int max(int a, int b) { return a > b ? a : b; }",
                "int max(int a, int b) { return a > b ? a : b; };;", Style);
 
   verifyFormat("class Foo {\n"
                "  int getSomething() const { return something; }\n"
                "};",
                "class Foo {\n"
                "  int getSomething() const { return something; };\n"
                "};",

clang/unittests/Format/FormatTestComments.cpp

TEST_F(FormatTestComments, AlignTrailingComments) {
 
   // https://llvm.org/PR53441
   verifyFormat("/* */  //\n"
                "int a; //\n");
   verifyFormat("/**/   //\n"
                "int a; //\n");
 }
 
+TEST_F(FormatTestComments, AlignTrailingCommentsAcrossEmptyLines) {
+  FormatStyle Style = getLLVMStyle();
+  Style.AlignTrailingComments.Kind = FormatStyle::TCAS_Always;
+  Style.AlignTrailingComments.OverEmptyLines = 1;
+  verifyFormat("#include \"a.h\"  // simple\n"
+               "\n"
+               "#include \"aa.h\" // example case\n",
+               Style);
+
+  verifyFormat("#include \"a.h\"   // align across\n"
+               "\n"
+               "#include \"aa.h\"  // two empty lines\n"
+               "\n"
+               "#include \"aaa.h\" // in a row\n",
+               Style);
+
+  verifyFormat("#include \"a.h\"      // align\n"
+               "#include \"aa.h\"     // comment\n"
+               "#include \"aaa.h\"    // blocks\n"
+               "\n"
+               "#include \"aaaa.h\"   // across\n"
+               "#include \"aaaaa.h\"  // one\n"
+               "#include \"aaaaaa.h\" // empty line\n",
+               Style);
+
+  verifyFormat("#include \"a.h\"  // align trailing comments\n"
+               "#include \"a.h\"\n"
+               "#include \"aa.h\" // across a line without comment\n",
+               Style);
+
+  verifyFormat("#include \"a.h\"   // align across\n"
+               "#include \"a.h\"\n"
+               "#include \"aa.h\"  // two lines without comment\n"
+               "#include \"a.h\"\n"
+               "#include \"aaa.h\" // in a row\n",
+               Style);
+
+  verifyFormat("#include \"a.h\"      // align\n"
+               "#include \"aa.h\"     // comment\n"
+               "#include \"aaa.h\"    // blocks\n"
+               "#include \"a.h\"\n"
+               "#include \"aaaa.h\"   // across\n"
+               "#include \"aaaaa.h\"  // a line without\n"
+               "#include \"aaaaaa.h\" // comment\n",
+               Style);
+
+  // Start of testing OverEmptyLines
+  Style.MaxEmptyLinesToKeep = 3;
+  Style.AlignTrailingComments.OverEmptyLines = 2;
+  // Cannot use verifyFormat here
+  // test::messUp removes all new lines which changes the logic
+  EXPECT_EQ("#include \"a.h\" // comment\n"
+            "\n"
+            "\n"
+            "\n"
+            "#include \"ab.h\"      // comment\n"
+            "\n"
+            "\n"
+            "#include \"abcdefg.h\" // comment\n",
+            format("#include \"a.h\" // comment\n"
+                   "\n"
+                   "\n"
+                   "\n"
+                   "#include \"ab.h\" // comment\n"
+                   "\n"
+                   "\n"
+                   "#include \"abcdefg.h\" // comment\n",
+                   Style));
+
+  Style.MaxEmptyLinesToKeep = 1;
+  Style.AlignTrailingComments.OverEmptyLines = 1;
+  // End of testing OverEmptyLines
+
+  Style.ColumnLimit = 15;
+  EXPECT_EQ("int ab; // line\n"
+            "int a;  // long\n"
+            "        // long\n"
+            "\n"
+            "        // long",
+            format("int ab; // line\n"
+                   "int a; // long long\n"
+                   "\n"
+                   "// long",
+                   Style));
+
+  Style.ColumnLimit = 15;
+  EXPECT_EQ("int ab; // line\n"
+            "\n"
+            "int a;  // long\n"
+            "        // long\n",
+            format("int ab; // line\n"
+                   "\n"
+                   "int a; // long long\n",
+                   Style));
+
+  Style.ColumnLimit = 30;
+  EXPECT_EQ("int foo = 12345; // comment\n"
+            "int bar =\n"
+            "    1234;  // This is a very\n"
+            "           // long comment\n"
+            "           // which is wrapped\n"
+            "           // arround.\n"
+            "\n"
+            "int x = 2; // Is this still\n"
+            "           // aligned?\n",
+            format("int foo = 12345; // comment\n"
+                   "int bar = 1234; // This is a very long comment\n"
+                   "                // which is wrapped arround.\n"
+                   "\n"
+                   "int x = 2; // Is this still aligned?\n",
+                   Style));
+
+  Style.ColumnLimit = 35;
+  EXPECT_EQ("int foo = 12345; // comment\n"
+            "int bar =\n"
+            "    1234; // This is a very long\n"
+            "          // comment which is\n"
+            "          // wrapped arround.\n"
+            "\n"
+            "int x =\n"
+            "    2; // Is this still aligned?\n",
+            format("int foo = 12345; // comment\n"
+                   "int bar = 1234; // This is a very long comment\n"
+                   "                // which is wrapped arround.\n"
+                   "\n"
+                   "int x = 2; // Is this still aligned?\n",
+                   Style));
+
+  Style.ColumnLimit = 40;
+  EXPECT_EQ("int foo = 12345; // comment\n"
+            "int bar =\n"
+            "    1234; // This is a very long comment\n"
+            "          // which is wrapped arround.\n"
+            "\n"
+            "int x = 2; // Is this still aligned?\n",
+            format("int foo = 12345; // comment\n"
+                   "int bar = 1234; // This is a very long comment\n"
+                   "                // which is wrapped arround.\n"
+                   "\n"
+                   "int x = 2; // Is this still aligned?\n",
+                   Style));
+
+  Style.ColumnLimit = 45;
+  EXPECT_EQ("int foo = 12345; // comment\n"
+            "int bar =\n"
+            "    1234;  // This is a very long comment\n"
+            "           // which is wrapped arround.\n"
+            "\n"
+            "int x = 2; // Is this still aligned?\n",
+            format("int foo = 12345; // comment\n"
+                   "int bar = 1234; // This is a very long comment\n"
+                   "                // which is wrapped arround.\n"
+                   "\n"
+                   "int x = 2; // Is this still aligned?\n",
+                   Style));
+
+  Style.ColumnLimit = 80;
+  EXPECT_EQ("int a; // line about a\n"
+            "\n"
+            "// line about b\n"
+            "long b;",
+            format("int a; // line about a\n"
+                   "\n"
+                   "       // line about b\n"
+                   "       long b;",
+                   Style));
+
+  Style.ColumnLimit = 80;
+  EXPECT_EQ("int a; // line about a\n"
+            "\n"
+            "// line 1 about b\n"
+            "// line 2 about b\n"
+            "long b;",
+            format("int a; // line about a\n"
+                   "\n"
+                   "       // line 1 about b\n"
+                   "       // line 2 about b\n"
+                   "       long b;",
+                   Style));
+}
+
+TEST_F(FormatTestComments, AlignTrailingCommentsLeave) {
+  FormatStyle Style = getLLVMStyle();
+  Style.AlignTrailingComments.Kind = FormatStyle::TCAS_Leave;
+
+  EXPECT_EQ("int a;// do not touch\n"
+            "int b; // any comments\n"
+            "int c;  // comment\n"
+            "int d;   // comment\n",
+            format("int a;// do not touch\n"
+                   "int b; // any comments\n"
+                   "int c;  // comment\n"
+                   "int d;   // comment\n",
+                   Style));
+
+  EXPECT_EQ("int a;   // do not touch\n"
+            "int b;  // any comments\n"
+            "int c; // comment\n"
+            "int d;// comment\n",
+            format("int a;   // do not touch\n"
+                   "int b;  // any comments\n"
+                   "int c; // comment\n"
+                   "int d;// comment\n",
+                   Style));
+
+  // Just format comments normally when leaving exceeds the column limit
+  Style.ColumnLimit = 35;
+  EXPECT_EQ("int foo = 12345; // comment\n"
+            "int bar =\n"
+            "    1234; // This is a very long\n"
+            "          // comment which is\n"
+            "          // wrapped arround.\n",
+            format("int foo = 12345; // comment\n"
+                   "int bar = 1234;       // This is a very long comment\n"
+                   "          // which is wrapped arround.\n",
+                   Style));
+}
+
 TEST_F(FormatTestComments, AlignsBlockCommentDecorations) {
   EXPECT_EQ("/*\n"
             " */",
             format("/*\n"
                    "*/",
                    getLLVMStyle()));
   EXPECT_EQ("/*\n"
             " */",

 
 TEST_F(FormatTestComments, SplitCommentIntroducers) {
   EXPECT_EQ(R"(//
 /\
 /
 )",
             format(R"(//
 /\
 / 
   )",
                    getLLVMStyleWithColumns(10)));
 }
 
 } // end namespace
 } // end namespace format
 } // end namespace clang