[WIP] A visual guide for rustfmt's configs (now at 100% coverage!)


#1

Rustfmt – at time of this writing – has around 65 configs ($ rustfmt --config-help) that can be customized to one’s personal style.

I was trying to improve rustfmt’s formatting style of a quite large project of mine today and got lost figuring out what each config did, shortly after, for a lack of code samples.

So I went ahead and wrote a quick visual guide based on my research:

There are still a bunch of configurations (10) and/or their respective code samples (18) missing (just ⌘f for FIXME). So if you happen to know what the missing configurations do and how to visualize their effect in a way that matches the rest of the code samples, or have any other kind of improvements, please feel free to make a PR. :kissing_heart:

Once complete there might be interest to merge the guide into the official rustfmt project, maybe? Also rustfmt appears to be lacking isolated tests for each config right now, for which the code samples might be a fitting starting point as well. Yay, nay … @nrc?


#2

I just pushed some commits …

  1. Improving existing code snippets.
  2. Adding missing FIXME markers.
  3. Improving the formatting of document.
  4. Adding cross-references between related configs.

I also added a tracking issue for the project’s completeness status:

… according to which the overall completeness is currently at 80%. :muscle:


#3

This is awesome. Thank you!


#4

I’m happy to announce that – roughly 1800 lines of Markdown later – the guide now covers :100:% of rustfmt’s supported configs. :sunglasses: :ok_hand:

While filling up the last gaps I stumbled upon three unexpected behaviors, which I suspect might actually be bugs:

  1. fn_args_density = "CompressedIfEmpty" appears to be broken in rustfmt
  2. where_indent appears to be ignored completely by rustfmt
  3. where_density = "Vertical" behaves like where_density = "Tall"

#5

Next step: Move it upstream. :construction_worker:


#6

This is fantastic, thank you! (Sorry it’s taken so long to notice - I’ve been on parental leave the last few weeks). I look forward to giving it a good read and merging it soon.


#7

No problem, Nick!

In the meanwhile I’ve turned the guide’s snippets into a total of 120 additional isolated unit tests :sunglasses: :

https://github.com/rust-lang-nursery/rustfmt/pull/1482

… along with some auxiliary drive-by PRs.

Please feel free to make any change requests. :slight_smile:


#8

6 PRs later we now have an official visual configs guide: :ok_hand:

And 120 additional unit tests at tests/source/configs-…. :tada:


#9

I like this guide, it’s quite easy to read and understand.

Some notes:

  • You show the Default value, Possible values and then you show examples of each possible value. I’d like the example of the default to be always at the top, and to have a “(default)” annotation attached after the default value. Like ““Visual” (default):”.

  • I don’t see the point of having indent_match_arms.

  • I’d like the default of spaces_around_ranges to be “true”, because it’s an operator and with spaces you can tell it better from a floating point literal.

  • for chain_indent I’d like a third option, to format code like this:

    let lorem = ipsum
    .dolor()
    .sit()
    .amet()
    .consectetur()
    .adipiscing()
    .elit();


#10

That’s nice to hear!

You have a very good point there. May I ask you to create an issue for that on the rustfmt repo to keep things centrally organized? If @nrc agrees with it I’ll try to create a PR for it when I find the time.

You might want to create an issue for rustfmt then, to get a discussion started there.

Personally I disagree, but this has been subject on fmt-rfcs already, regardless.

Quoting @nrc from said issue:

My current thinking is that not having spaces in ranges is more common and there is not really overwhelming support evidence to change that. IMO, it is the right choice, but this seems to come down to a subjective aesthetic choice, and possibly how often you use ranges with atomic vs compound expressions.

I propose that we keep no spaces.

This, too, should be discussed on fmt-rfcs, I think.

Thanks for your interest, @leonardo! :+1:


#11

I have just submitted: