Autobrace for loops, while loops, repeat loops, and function definitions

[DavisVaughan]

Branched from #340

Added autobracing to:

• for loops
• while loops
• repeat loops
• function definitions

These are significantly less complicated than if/else handling because we don't have to worry about nesting (like if (cond) 1 else if (cond) 2 else 3).

We unconditionally autobrace the body of all loop types. As discussed, we don't see a use case for 1 line loops that would be more clear without braces.

Function definitions are allowed on one line. Braces will be added if any part of the function definition spans multiple lines (the parameters or the body).

---

The comment handling of all of these types needed a bit of an overhaul, so there's a decent amount of churn there. We more comprehensively handle all possible comment positions now, and I've added a slew of new comment related tests to ensure we don't break anything in the future.

---

I've added the CHANGELOG bullet for this feature here, along with a new Autobracing section in the documentation.

Addition of "most flat" variant

The most subtle but also most impactful change here is that I've had to touch call_arguments.rs.

Consider the following two map() calls:

map(xs, function(x) x + 1)

map(xs, function(x) {
  x + 1
})

Previously, we would only consider a function definition eligible for the "best fitting" algorithm if its body already had {. So only the second would be considered as a candidate for "best fitting". The first would have chosen between a call with no breaks at all, or a call that is completely expanded.

Best fitting in theory chooses between 3 layouts:

• Most flat variant
• Middle variant (the special form you see above)
• Most expanded variant (fully expanded function call)

Because we required {, this actually immediately ruled out the most flat variant. I've always had the intention of adding it back in when we needed it, but up until now it was in a branch that was unreachable!().

We now need to consider the most flat variant, because we've changed the function definition rule from "only do best fitting if it has { in the body" to "always try best fitting". That means for something like this:

map(xs, function(x) x + something_really_really_long_here_exceeding_line_length)

we now decide between:

# most flat
map(xs, function(x) x + something_really_really_long_here_exceeding_line_length)

# middle variant
map(xs, function(x) {
  x + something_really_really_long_here_exceeding_line_length
})

# most expanded (may or may not autobrace depending on line length)
map(
  xs,
  function(x) {
    x + something_really_really_long_here_exceeding_line_length
  }
)

this also allows the cool "code reflow" move of putting a line break here:

map(xs, function(x) <here>x + 1)

to get

map(xs, function(x) {
  x + 1
})

---

Even before autobracing, I think it was actually a mistake that we required { as a prerequisite for trying the best fitting algorithm. Like, this doesn't have { and probably should have gone through the best fitting algorithm so it could select the middle variant (which is the form you see here):

map(xs, function(x) 
  x + y + z + this_other_long_thing
)

This will now get autobraced to

map(xs, function(x) {
  x + y + z + this_other_long_thing
})