Add ReflowComments rule

[itingliu]

This opt-in rule joins comments that were hard-wrapped across multiple
lines back into a single line when the combined text still fits within
the configured line length.

It reflows only line comments (//) and documentation line comments
(///), and only joins lines that belong to the same Markdown paragraph.
Lists, headings, code blocks, block quotes, thematic breaks, blank lines
between paragraphs, divider lines such as //===----===//, and file
headers are left untouched. The reflowComments.reflowedCommentKinds and
reflowComments.preservedLinePrefixes options control which comments the
rule reflows.

[itingliu]

Resolves #1235

[allevato]

Thanks for taking a look at this!

I think the problem is a bit trickier than it appears, and a pure syntax-node-based rule isn't going to suffice I'm afraid. Since this behavior deals with line breaking/reflowing, it can't really be applied until the pretty printer phase. Consider this example:

struct S {
func f() {
// these lines are intentionally unindented, assume the column
// width is 80 and these lines will go past column 80
}
}

swift-format works in two discrete phases:

• First, syntax-node-based rules are applied. These only deal with structural correctness, not line breaking or indentation.
• Second, the pretty printer reflows the tokens based on line breaking rules, recomputing indentation and taking column width into account.

Since ReflowComments is a node-based rule, it will run before the correct indentation for those lines is known. Assuming an indentation width of 2 spaces, if you reflow this comment in its current form, you're reflowing it based on its current incorrect indentation (zero) and effectively granting it 4 more spaces than it should actually have once properly indented.

I think the proper (and only correct) way to do this is to update the pretty printer to treat clusters of whole-line comments as atomic units. The place to start would be looking at how we handle comments in TokenStreamCreator and PrettyPrinter. For block comments, we already gather the whole (multiline) comment as a block so that we can write it back out. For line comments, we only take a line at a time. I think what we'd need to do instead is fold multiple line comments into a single Comment value to pass to the pretty printer. Then when we process that formatting token in the pretty printer, it's happening right before we're supposed to print it back out, so we know the exact current indentation and the column limit and we can compute the difference to get the correct width for the text.

[itingliu]

I think the proper (and only correct) way to do this is to update the pretty printer to treat clusters of whole-line comments as atomic units. The place to start would be looking at how we handle comments in TokenStreamCreator and PrettyPrinter. For block comments, we already gather the whole (multiline) comment as a block so that we can write it back out. For line comments, we only take a line at a time. I think what we'd need to do instead is fold multiple line comments into a single Comment value to pass to the pretty printer. Then when we process that formatting token in the pretty printer, it's happening right before we're supposed to print it back out, so we know the exact current indentation and the column limit and we can compute the difference to get the correct width for the text.

Thanks for the pointer! I underestimated this overwhelmingly since indentation has never been a problem in the repos that I work with 😅

I'll take a stab with this direction and come back with whatever I have. Thanks!