Add documentation on why we don't support "hanging indent" style

[Yunuuuu]

I would love to something like this:

fn <- function(long_long_long_long_long_long_long_arg1,
               long_long_long_long_long_long_long_arg2) {
    
}

But air gave me this:

fn <- function(
    long_long_long_long_long_long_long_arg1,
    long_long_long_long_long_long_long_arg2
) {
}

[DavisVaughan]

In Air we do not allow the "hanging indent" style in your first example in function definitions or function calls.

We haven't added the official docs about this, but we have old docs in here about this:
https://github.com/posit-dev/air/blob/main/docs-old/formatter.md#function-definition-styles

Notably, hanging indent is bad for accessibility if you switch to using tabs:
https://github.com/posit-dev/air/blob/main/docs-old/formatter.md#mixing-tabs-and-spaces

It also makes it significantly more complex to have 3 layouts (flat, hanging, expanded) in the formatter. I don't think our persistent line breaks feature would be possible if we supported this

[DavisVaughan]

Keeping open so we can add docs about it

[juliasilge]

The main thing that convinced me I don't actually want hanging indents is rainbow tabs 🌈 😆

[DavisVaughan]

TRUE

[Yunuuuu]

Or if it could be possible to skip a single line like styler:

fn <- function(long_long_long_long_long_long_long_arg1,    # fmt: skip
               long_long_long_long_long_long_long_arg2) {  # fmt: skip
    # the inner block should be formated
    if (    TRUE &&        FALSE) {
}
}

[DavisVaughan]

# fmt: skip applies to nodes not lines, so in this case # fmt: skip is getting attached to long_long_long_long_long_long_long_arg1 itself (imagine it was 1+1, that would not get formatted).

But even so, I don't think we would encourage doing this. If you want to use Air, then I'd likely to respectfully encourage you to give this new expanded format a chance. For me (who has been doing hanging indent for years), it started to feel natural very quickly. It is also extremely similar to how many other languages format their function signatures, making it ever so slightly easier to cross between languages.

I also think it makes your example easier to read

fn <- function(
  long_long_long_long_long_long_long_arg1,
  long_long_long_long_long_long_long_arg2
) {
  # the inner block should be formated
  if (TRUE && FALSE) {
  }
}

i.e. your eyes scan straight down the page when reading the function from top to bottom, rather than having to look off to the right a little to read the arguments and then move back to the left to read the body of the function. This is obviously all a little subjective and hand wavy but the overall indentation level of the styled code is something we think about for reasons like this one.