Merge pull request #2307 from clarcharr/master

Rearrange README.md.

Author: oli-obk

README.md

@@ -26,18 +26,35 @@ as an included feature during build. All of these options are detailed below.
 
 As a general rule clippy will only work with the *latest* Rust nightly for now.
 
-### Optional dependency
+### As a cargo subcommand (`cargo clippy`)
+
+One way to use clippy is by installing clippy through cargo as a cargo
+subcommand.
+
+```terminal
+cargo install clippy
+```
+
+Now you can run clippy by invoking `cargo clippy`, or
+`cargo +nightly clippy` directly from a directory that is usually
+compiled with stable.
+
+In case you are not using rustup, you need to set the environment flag
+`SYSROOT` during installation so clippy knows where to find `librustc` and
+similar crates.
+
+```terminal
+SYSROOT=/path/to/rustc/sysroot cargo install clippy
+```
 
-If you want to make clippy an optional dependency, you can do the following:
+### Optional dependency
 
-In your `Cargo.toml`:
+In some cases you might want to include clippy in your project directly, as an
+optional dependency. To do this, just modify `Cargo.toml`:
 
 ```toml
 [dependencies]
-clippy = {version = "*", optional = true}
-
-[features]
-default = []
+clippy = { version = "*", optional = true }
 ```
 
 And, in your `main.rs` or `lib.rs`, add these lines:
@@ -54,25 +71,18 @@ Instead of adding the `cfg_attr` attributes you can also run clippy on demand:
 (the `-Z no trans`, while not necessary, will stop the compilation process after
 typechecking (and lints) have completed, which can significantly reduce the runtime).
 
-### As a cargo subcommand (`cargo clippy`)
+Alternatively, to only run clippy when testing:
 
-An alternate way to use clippy is by installing clippy through cargo as a cargo
-subcommand.
-
-```terminal
-cargo install clippy
+```toml
+[dev-dependencies]`
+clippy = { version = "*" }
 ```
 
-Now you can run clippy by invoking `cargo clippy`, or
-`rustup run nightly cargo clippy` directly from a directory that is usually
-compiled with stable.
+and add to `main.rs` or  `lib.rs`:
 
-In case you are not using rustup, you need to set the environment flag
-`SYSROOT` during installation so clippy knows where to find `librustc` and
-similar crates.
-
-```terminal
-SYSROOT=/path/to/rustc/sysroot cargo install clippy
+```
+#![cfg_attr(test, feature(plugin))]
+#![cfg_attr(test, plugin(clippy))]
 ```
 
 ### Running clippy from the command line without installing