refactor and document the chain reformatting code

[rust.git] / README.md

diff --git a/README.md b/README.md
index b8344ac770cdeb8897999a63223203502c449ab7..d2dc9a22f8511e432b74b920273bc577d1e98563 100644 (file)
--- a/README.md
+++ b/README.md
@@ -53,20 +53,28 @@ binary and library targets of your crate.
 You'll probably want to specify the write mode. Currently, there are modes for
 diff, replace, overwrite, display, coverage, and checkstyle.
 
-* `replace` Is the default and overwrites the original files after renaming them.
-* `overwrite` rustfmt does not backup the source files.
-* `display` Will print the formatted file to stdout.
-* `diff` Will print a diff between the current file and formatted file to stdout.
+* `replace` Is the default and overwrites the original files after creating backups of the files.
+* `overwrite` Overwrites the original files _without_ creating backups.
+* `display` Will print the formatted files to stdout.
+* `diff` Will print a diff between the original files and formatted files to stdout.
 * `checkstyle` Will output the lines that need to be corrected as a checkstyle XML file,
   that can be used by tools like Jenkins.
 
 The write mode can be set by passing the `--write-mode` flag on
 the command line. For example `rustfmt --write-mode=display src/filename.rs`
 
-You can run `rustfmt --help` for more information.
-
 `cargo fmt` uses `--write-mode=replace` by default.
 
+If `rustfmt` successfully reformatted the code it will exit with `0` exit
+status. Exit status `1` signals some unexpected error, like an unknown option or
+a failure to read a file. Exit status `2` is returned if there are syntax errors
+in the input files. `rustfmt` can't format syntatically invalid code. Finally,
+exit status `3` is returned if there are some issues which can't be resolved
+automatically. For example, if you have a very long comment line `rustfmt`
+doesn't split it. Instead it prints a warning and exits with `3`.
+
+You can run `rustfmt --help` for more information.
+
 
 ## Running Rustfmt from your editor
 
@@ -90,7 +98,7 @@ notes above on running rustfmt.
 
 Rustfmt is designed to be very configurable. You can create a TOML file called
 rustfmt.toml, place it in the project directory and it will apply the options
-in that file. See `cargo run -- --config-help` for the options which are available,
+in that file. See `rustfmt --config-help` for the options which are available,
 or if you prefer to see source code, [src/config.rs](src/config.rs).
 
 By default, Rustfmt uses a style which (mostly) conforms to the
@@ -110,10 +118,18 @@ options covering different styles. File an issue, or even better, submit a PR.
 * For things you do not want rustfmt to mangle, use one of
 
     ```rust
-    #[rustfmt_skip]
-    #[cfg_attr(rustfmt, rustfmt_skip)]
+    #[rustfmt_skip]  // requires nightly and #![feature(custom_attribute)] in crate root
+    #[cfg_attr(rustfmt, rustfmt_skip)]  // works in stable
     ```
 * When you run rustfmt, place a file named rustfmt.toml in target file
   directory or its parents to override the default settings of rustfmt.
 * After successful compilation, a `rustfmt` executable can be found in the
   target directory.
+
+
+## License
+
+Rustfmt is distributed under the terms of both the MIT license and the
+Apache License (Version 2.0).
+
+See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.