Fix the documentation of the unstable_features option.

[krtab]

The documentation of the unstable_feature options does not match anymore its behavior, as explained in: #5169.

Fixes: #5169

Ref: #3387

[ytmimi]

I did some digging and it turns out that the --unstable_features flag turns on whether or not you can pass --skip-children, --error-on-unformatted or --file-lines via the command line. Here's the reference in the source code

Try running: rustfmt +nightly --skip-children --error-on-unformatted --file-lines "[]" and you'll get the following output:

Unstable options (`--skip-children`, `--error-on-unformatted`, `--file-lines`) used without `--unstable-features`

Also note the (unstable) output for these options using of rustfmt +nightly --help (emphasis with '*' added by me):

        --file-lines JSON
                        Format specified line ranges. Run with
                        `--help=file-lines` for more detail **(unstable)**.
        --error-on-unformatted 
                        Error if unable to get comments or string literals
                        within max_width, or they are left with trailing
                        whitespaces **(unstable)**.
        --skip-children 
                        Don't reformat child modules **(unstable)**.

Trying to run rustfmt +stable --skip-children, rustfmt +stable --error-on-unformatted, or rustfmt +stable --file-lines "[]" results in an error because these options are only added to the command line interface on nightly :

Unrecognized option: 'skip-children'
Unrecognized option: 'error-on-unformatted'
Unrecognized option: 'file-lines'

[ytmimi]

@krtab Thanks again for your PR. Do you have any interest in updating the docs to include the details I listed above?

[krtab]

Hi, sorry for the long response time. Do you know why these three unstable options get a peculiar treatment ? Wouldn't it make sense to unify the treatment of unstable options to either fully deprecate or use the --unstable-features flag?

[ytmimi]

@krtab unfortunately I don't have any context for why these three options are gated in the CLI via the --unstable-features flag as they were added before I joined the team. @calebcartwright do you have any additional knowledge of why these options are given special treatment?

[calebcartwright]

@krtab unfortunately I don't have any context for why these three options are gated in the CLI via the --unstable-features flag as they were added before I joined the team. @calebcartwright do you have any additional knowledge of why these options are given special treatment?

First I just want to share the likely unsavory news that we need to put this on pause for the moment. We need to figure out the direction we need to have for the behavior before making any changes to documentation, even if the documentation doesn't match current behavior.

As to the question, I don't recall off hand. There's been some waffling back and forth around unstable on stable, command line vs. config, etc. that's largely happened in isolation independent of behavior in other dev tools, and it's something we need to reconcile.

[krtab]

OK no worries if you want to put that on old, feel free to close the PR.