Update Configurations.md

[topecongiro]

Some examples in Configurations.md are outdated and use the legacy style.
We should update them to use the Rfc style.

[paulsevere]

I would like to take a stab at this.

[nrc]

@paulsevere great, thank you! The best way I think to tackle this is to work through the examples and check how they are formatted with the default configuration (i.e., no rustfmt.toml) and then update the text and examples as you find differences.

@topecongiro may have noticed some that need changing in particular. I would start with any options/examples that affect function signatures since I think that is where there are the most obvious changes.

[paulsevere]

Just to clarify, I am looking for deviations from the default formatting conventions that are not demonstrations of an alternative formatting rule?

eg.
In the following snippet demonstrating the return_Indent rule :

fn lorem(ipsum: Ipsum,
         dolor: Dolor,
         sit: Sit,
         amet: Amet,
         consectetur: Consectetur,
         adipiscing: Adipiscing)
         -> Elit
    where Ipsum: Eq
{
    // body
}

The function arguments are formatted in accordance with fn_args_layout = "Visual" and should be corrected to :

fn lorem(
    ipsum: usize,
    dolor: usize,
    sit: usize,
    amet: usize,
    consectetur: usize,
    adipiscing: usize,
    elit: usize,
) {
    // body
}

[nrc]

@paulsevere yeah, that is exactly the sort of thing to look for. I think that for nearly all examples, the code you see in the markdown should match exactly the output of Rustfmt with the given config options (or no options, if the default). In some cases, there are some other options required for the option being demonstrated to take effect. (I think this could probably be done automatically, but it would require some work).

[nrc]

@paulsevere Hey, how did you get along with this? Did you find major differences?

[davidalber]

How would you feel about making the examples in Configurations.md automatically validated so that we don't have to worry about manually detecting inconsistencies in the future?

I can think of a few ways to approach this, but none of them are going to be as seamless to work with as a static file. Here are some ideas:

• Assemble the Configurations.md file from a base file and several files containing the code examples. The code examples can be validated using the existing idempotency test framework, which will let us know when examples become outdated. We would somehow indicate the examples need to be included in the base file, and a tool would generate Configurations.md at the top level of the repo.
• Keep Configurations.md the same, but have a process by which we have code examples duplicated into test cases to test for idempotency. This will suffer from omissions and inconsistencies since it depends on a human-enforced process. Maybe there could be something that enforces the pairing with a test case.
• Do something along the lines of format rust code examples inside docs #1695 that allows us to test the code blocks in place for idempotency. One apparent downside is that we would need to put the test attributes (i.e., the configuration settings) inside the code blocks, making them visible to readers of Configurations.md. Maybe that's fine, but it could be a little distracting.

[nrc]

How would you feel about making the examples in Configurations.md automatically validated

I think that would be great!

The third option is my favourite, but probably the hardest. I think that for testing we could special-case Configurations.md in the testing code so that it tries to read the options from the text surrounding the code.

[davidalber]

I started poking around with this. I don't want to step on @paulsevere's toes, in case he is still planning to work on this, but I'll talk about my work in progress for feedback.

At this point I have a new test that calls a helper function. This function produces a Vec of a struct that stores information about each code block in Configurations.md. It extracts the configuration name and value from the markdown. The next most obvious thing to do will be to figure out to get rustfmt to format the extracted code blocks.

I'll also want to have a way to opt code blocks out of the check, perhaps by using a markdown comment right above the code block. Maybe something like

<!-- rustfmt = false; -->

I'm assuming that rustfmt will be unable to format many of the current snippets because they need to be wrapped in functions. We'll need to decide if we either want to modify the snippets to be legal or make it possible for the test to handle this transparently behind the scenes transparently.

[nrc]

I'll also want to have a way to opt code blocks out of the check

You could distinguish between triple-back-tick code blocks (don't format) and triple-back-tick rust blocks which you do format. Otherwise, the comment seems fine - we already use comments in the test input files to control options, so you should try and be as close as possible to that format.

We could probably add fn main() { ... } around all the expression snippets in order to make them formattable. I think that would be the best solution.

[davidalber]

You could distinguish between triple-back-tick code blocks (don't format) and triple-back-tick rust blocks which you do format.

Good call. With that, I don't expect -- at this time -- to need to add any comments. The options are being extracted from the non-code-block Markdown, which is possible because the file's format is so consistent.

We could probably add fn main() { ... } around all the expression snippets in order to make them formattable. I think that would be the best solution.

👍