Update documentation (#4345)

ayazhafiz · web-flow · commit a190c4b767d3 · 2020-07-28T11:40:50.000-05:00
* Update documentation This commit includes changes to the readme, cargo-fmt, and rustfmt - Readme - rearrange sections to an order I believe is a more natural progression (this is opinionated, open to suggestions) - add a TOC (I can add a CI test to ensure it's up to date, lmk what you think) - cargo-fmt - link to config options - rustfmt - elaborate on operation with files/stdin - include examples - link to config options Closes #4336 * fixup! Update documentation * fixup! Update documentation * fixup! Update documentation
diff --git a/README.md b/README.md
@@ -1,5 +1,27 @@
 # rustfmt [![Linux badge][linux-build-status]][linux-build] [![Mac badge][mac-build-status]][mac-build] [![Windows badge][windows-build-status]][windows-build] [![crates.io badge][cratesio-badge]][cratesio-package] [![Travis config badge][travis-config-badge]][travis-config-job]
 
+<!-- To update: doctoc README.md --notitle -->
+<!-- https://github.com/thlorenz/doctoc -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Quick start](#quick-start)
+  - [On the Stable toolchain](#on-the-stable-toolchain)
+  - [On the Nightly toolchain](#on-the-nightly-toolchain)
+  - [Installing from source](#installing-from-source)
+- [Running](#running)
+- [Configuring Rustfmt](#configuring-rustfmt)
+  - [Rust's Editions](#rusts-editions)
+- [Limitations](#limitations)
+- [Running Rustfmt from your editor](#running-rustfmt-from-your-editor)
+- [Checking style on a CI server](#checking-style-on-a-ci-server)
+- [How to build and test](#how-to-build-and-test)
+- [Tips](#tips)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 A tool for formatting Rust code according to style guidelines.
 
 If you'd like to help out (and you should, it's a fun project!), see
@@ -45,42 +67,7 @@ To run on a cargo project in the current working directory:
 cargo +nightly fmt
 ```
 
-## Limitations
-
-Rustfmt tries to work on as much Rust code as possible. Sometimes, the code
-doesn't even need to compile! As we approach a 1.0 release we are also looking
-to limit areas of instability; in particular, post-1.0, the formatting of most
-code should not change as Rustfmt improves. However, there are some things that
-Rustfmt can't do or can't do well (and thus where formatting might change
-significantly, even post-1.0). We would like to reduce the list of limitations
-over time.
-
-The following list enumerates areas where Rustfmt does not work or where the
-stability guarantees do not apply (we don't make a distinction between the two
-because in the future Rustfmt might work on code where it currently does not):
-
-* a program where any part of the program does not parse (parsing is an early
-  stage of compilation and in Rust includes macro expansion).
-* Macro declarations and uses (current status: some macro declarations and uses
-  are formatted).
-* Comments, including any AST node with a comment 'inside' (Rustfmt does not
-  currently attempt to format comments, it does format code with comments inside, but that formatting may change in the future).
-* Rust code in code blocks in comments.
-* Any fragment of a program (i.e., stability guarantees only apply to whole
-  programs, even where fragments of a program can be formatted today).
-* Code containing non-ascii unicode characters (we believe Rustfmt mostly works
-  here, but do not have the test coverage or experience to be 100% sure).
-* Bugs in Rustfmt (like any software, Rustfmt has bugs, we do not consider bug
-  fixes to break our stability guarantees).
-
-
-## Installation
-
-```sh
-rustup component add rustfmt
-```
-
-## Installing from source
+### Installing from source
 
 To install from source (nightly required), first checkout to the tag or branch for the version of rustfmt you want. 
 
@@ -102,25 +89,75 @@ cargo install --path . --force --locked --features rustfmt,cargo-fmt
 This will install `rustfmt` in your `~/.cargo/bin`. Make sure to add `~/.cargo/bin` directory to
 your PATH variable.
 
-
 ## Running
 
+You can run `rustfmt --help` for information about available arguments.
+
 You can run Rustfmt by just typing `rustfmt filename` if you used `cargo
 install`. This runs rustfmt on the given file, if the file includes out of line
 modules, then we reformat those too. So to run on a whole module or crate, you
 just need to run on the root file (usually mod.rs or lib.rs). Rustfmt can also
 read data from stdin. Alternatively, you can use `cargo fmt` to format all
 binary and library targets of your crate.
 
-You can run `rustfmt --help` for information about available arguments.
-
 When running with `--check`, Rustfmt will exit with `0` if Rustfmt would not
 make any formatting changes to the input, and `1` if Rustfmt would make changes.
 In other modes, Rustfmt will exit with `1` if there was some error during
 formatting (for example a parsing or internal error) and `0` if formatting
 completed without error (whether or not changes were made).
 
+## Configuring Rustfmt
+
+Rustfmt is designed to be very configurable. You can create a TOML file called
+`rustfmt.toml` or `.rustfmt.toml`, place it in the project or any other parent
+directory and it will apply the options in that file. See `rustfmt
+--help=config` for the options which are available, or if you prefer to see
+visual style previews, [GitHub page](https://rust-lang.github.io/rustfmt/).
+
+By default, Rustfmt uses a style which conforms to the [Rust style guide][style
+guide] that has been formalized through the [style RFC
+process][fmt rfcs].
+
+Configuration options are either stable or unstable. Stable options can always
+be used on any channel. Unstable options are always available on nightly, but can only be used on stable and beta with an explicit opt-in (starting in Rustfmt v2.0).
+
+Unstable options are not available on stable/beta with Rustfmt v1.x.
+
+See the configuration documentation on the Rustfmt [GitHub page](https://rust-lang.github.io/rustfmt/) for details (look for the `unstable_features` section).
+
+### Rust's Editions
+
+Rustfmt is able to pick up the edition used by reading the `Cargo.toml` file if
+executed through the Cargo's formatting tool `cargo fmt`. Otherwise, the edition
+needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`.
+
+## Limitations
+
+Rustfmt tries to work on as much Rust code as possible. Sometimes, the code
+doesn't even need to compile! As we approach a 1.0 release we are also looking
+to limit areas of instability; in particular, post-1.0, the formatting of most
+code should not change as Rustfmt improves. However, there are some things that
+Rustfmt can't do or can't do well (and thus where formatting might change
+significantly, even post-1.0). We would like to reduce the list of limitations
+over time.
 
+The following list enumerates areas where Rustfmt does not work or where the
+stability guarantees do not apply (we don't make a distinction between the two
+because in the future Rustfmt might work on code where it currently does not):
+
+* a program where any part of the program does not parse (parsing is an early
+  stage of compilation and in Rust includes macro expansion).
+* Macro declarations and uses (current status: some macro declarations and uses
+  are formatted).
+* Comments, including any AST node with a comment 'inside' (Rustfmt does not
+  currently attempt to format comments, it does format code with comments inside, but that formatting may change in the future).
+* Rust code in code blocks in comments.
+* Any fragment of a program (i.e., stability guarantees only apply to whole
+  programs, even where fragments of a program can be formatted today).
+* Code containing non-ascii unicode characters (we believe Rustfmt mostly works
+  here, but do not have the test coverage or experience to be 100% sure).
+* Bugs in Rustfmt (like any software, Rustfmt has bugs, we do not consider bug
+  fixes to break our stability guarantees).
 
 ## Running Rustfmt from your editor
 
@@ -131,7 +168,6 @@ completed without error (whether or not changes were made).
 * Visual Studio Code using [vscode-rust](https://github.com/editor-rs/vscode-rust), [vsc-rustfmt](https://github.com/Connorcpu/vsc-rustfmt) or [rls_vscode](https://github.com/jonathandturner/rls_vscode) through RLS.
 * [IntelliJ or CLion](intellij.md)
 
-
 ## Checking style on a CI server
 
 To keep your code base consistently formatted, it can be helpful to fail the CI build
@@ -197,32 +233,6 @@ CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo test --all-features
 To run rustfmt after this, use `cargo run --bin rustfmt -- filename`. See the
 notes above on running rustfmt.
 
-
-## Configuring Rustfmt
-
-Rustfmt is designed to be very configurable. You can create a TOML file called
-`rustfmt.toml` or `.rustfmt.toml`, place it in the project or any other parent
-directory and it will apply the options in that file. See `rustfmt
---help=config` for the options which are available, or if you prefer to see
-visual style previews, [GitHub page](https://rust-lang.github.io/rustfmt/).
-
-By default, Rustfmt uses a style which conforms to the [Rust style guide][style
-guide] that has been formalized through the [style RFC
-process][fmt rfcs].
-
-Configuration options are either stable or unstable. Stable options can always
-be used on any channel. Unstable options are always available on nightly, but can only be used on stable and beta with an explicit opt-in (starting in Rustfmt v2.0).
-
-Unstable options are not available on stable/beta with Rustfmt v1.x.
-
-See the configuration documentation on the Rustfmt [GitHub page](https://rust-lang.github.io/rustfmt/) for details (look for the `unstable_features` section).
-
-### Rust's Editions
-
-Rustfmt is able to pick up the edition used by reading the `Cargo.toml` file if
-executed through the Cargo's formatting tool `cargo fmt`. Otherwise, the edition
-needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`.
-
 ## Tips
 
 * For things you do not want rustfmt to mangle, use `#[rustfmt::skip]`
diff --git a/src/cargo-fmt/main.rs b/src/cargo-fmt/main.rs
@@ -47,6 +47,9 @@ pub struct Opts {
     message_format: Option<String>,
 
     /// Options passed to rustfmt
+    ///
+    /// To see all rustfmt options, run `rustfmt --help'.
+    /// To see all rustfmt configuration options, please visit https://rust-lang.github.io/rustfmt.
     // 'raw = true' to make `--` explicit.
     #[structopt(name = "rustfmt_options", raw(true))]
     rustfmt_options: Vec<String>,
diff --git a/src/rustfmt/main.rs b/src/rustfmt/main.rs
@@ -43,7 +43,30 @@ fn main() {
 
 /// Format Rust code
 #[derive(Debug, StructOpt, Clone)]
-#[structopt(name = "rustfmt", version = include_str!(concat!(env!("OUT_DIR"),"/version-info.txt")))]
+#[structopt(
+    name = "rustfmt",
+    version = include_str!(concat!(env!("OUT_DIR"),"/version-info.txt")),
+    about = r#"Format Rust code
+
+Rustfmt runs on a set of files or stdin. When invoked without any file arguments, rustfmt will
+read code from stdin.
+
+Please visit https://rust-lang.github.io/rustfmt to see all rustfmt configuration options.
+
+EXAMPLES
+
+    cat lib.rs | rustfmt
+        Feed the contents of "lib.rs" to rustfmt via stdin
+
+    rustfmt lib.rs main.rs
+        Run rustfmt over "lib.rs" and "main.rs", formatting in-place.
+
+    rustfmt --emit=stdout lib.rs main.rs
+        Run rustfmt over "lib.rs" and "main.rs", writing to stdout (rather than in-place)
+
+    rustfmt --config-path=rustfmt.toml --print-config=current
+        Print the resolved rustfmt configuration formed by rustfmt.toml
+"#)]
 struct Opt {
     /// Run in 'check' mode.
     ///
@@ -60,7 +83,8 @@ struct Opt {
     config_path: Option<PathBuf>,
     /// Rust compiler edition
     ///
-    /// Specify which edition of the compiler to use when formatting code.
+    /// Specify which edition of the compiler to use when formatting code. This behaves identically
+    /// to the "edition" configuration option.
     #[structopt(long, name = "2015|2018")]
     edition: Option<Edition>,
     /// Print configuration options.
