Merge pull request #1345 from EpocSquadron/epocsquadron-documentation

Clarify recco to install as a soft dependency

Author: Manishearth

README.md

@@ -16,52 +16,41 @@ Table of contents:
 
 ## Usage
 
+Since this is a tool for helping the developer of a library or application
+write better code, it is recommended not to include clippy as a hard dependency.
+Options include using it as an optional dependency, as a cargo subcommand, or
+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.
 
-### As a Compiler Plugin
+### Optional dependency
 
-Since stable Rust is backwards compatible, you should be able to
-compile your stable programs with nightly Rust with clippy plugged in to
-circumvent this.
+If you want to make clippy an optional dependency, you can do the following:
 
-Add in your `Cargo.toml`:
+In your `Cargo.toml`:
 
 ```toml
 [dependencies]
-clippy = "*"
-```
+clippy = {version = "*", optional = true}
 
-You then need to add `#![feature(plugin)]` and `#![plugin(clippy)]` to the top
-of your crate entry point (`main.rs` or `lib.rs`).
+[features]
+default = []
+```
 
-Sample `main.rs`:
+And, in your `main.rs` or `lib.rs`:
 
 ```rust
-#![feature(plugin)]
-
-#![plugin(clippy)]
-
+#![cfg_attr(feature="clippy", feature(plugin))]
 
-fn main(){
-    let x = Some(1u8);
-    match x {
-        Some(y) => println!("{:?}", y),
-        _ => ()
-    }
-}
+#![cfg_attr(feature="clippy", plugin(clippy))]
 ```
 
-Produces this warning:
+Then build by enabling the feature: `cargo build --features "clippy"`
 
-```terminal
-src/main.rs:8:5: 11:6 warning: you seem to be trying to use match for destructuring a single type. Consider using `if let`, #[warn(single_match)] on by default
-src/main.rs:8     match x {
-src/main.rs:9         Some(y) => println!("{:?}", y),
-src/main.rs:10         _ => ()
-src/main.rs:11     }
-src/main.rs:8:5: 11:6 help: Try
-if let Some(y) = x { println!("{:?}", y) }
-```
+Instead of adding the `cfg_attr` attributes you can also run clippy on demand:
+`cargo rustc --features clippy -- -Z no-trans -Z extra-plugins=clippy`
+(the `-Z no trans`, while not neccessary, will stop the compilation process after
+typechecking (and lints) have completed, which can significantly reduce the runtime).
 
 ### As a cargo subcommand (`cargo clippy`)
 
@@ -96,34 +85,52 @@ cargo rustc -- -L /path/to/clippy_so -Z extra-plugins=clippy
 *[Note](https://github.com/Manishearth/rust-clippy/wiki#a-word-of-warning):*
 Be sure that clippy was compiled with the same version of rustc that cargo invokes here!
 
-### Optional dependency
+### As a Compiler Plugin
 
-If you want to make clippy an optional dependency, you can do the following:
+*Note:* This is not a recommended installation method.
 
-In your `Cargo.toml`:
+Since stable Rust is backwards compatible, you should be able to
+compile your stable programs with nightly Rust with clippy plugged in to
+circumvent this.
+
+Add in your `Cargo.toml`:
 
 ```toml
 [dependencies]
-clippy = {version = "*", optional = true}
-
-[features]
-default = []
+clippy = "*"
 ```
 
-And, in your `main.rs` or `lib.rs`:
+You then need to add `#![feature(plugin)]` and `#![plugin(clippy)]` to the top
+of your crate entry point (`main.rs` or `lib.rs`).
+
+Sample `main.rs`:
 
 ```rust
-#![cfg_attr(feature="clippy", feature(plugin))]
+#![feature(plugin)]
 
-#![cfg_attr(feature="clippy", plugin(clippy))]
+#![plugin(clippy)]
+
+
+fn main(){
+    let x = Some(1u8);
+    match x {
+        Some(y) => println!("{:?}", y),
+        _ => ()
+    }
+}
 ```
 
-Then build by enabling the feature: `cargo build --features "clippy"`
+Produces this warning:
 
-Instead of adding the `cfg_attr` attributes you can also run clippy on demand:
-`cargo rustc --features clippy -- -Z no-trans -Z extra-plugins=clippy`
-(the `-Z no trans`, while not neccessary, will stop the compilation process after
-typechecking (and lints) have completed, which can significantly reduce the runtime).
+```terminal
+src/main.rs:8:5: 11:6 warning: you seem to be trying to use match for destructuring a single type. Consider using `if let`, #[warn(single_match)] on by default
+src/main.rs:8     match x {
+src/main.rs:9         Some(y) => println!("{:?}", y),
+src/main.rs:10         _ => ()
+src/main.rs:11     }
+src/main.rs:8:5: 11:6 help: Try
+if let Some(y) = x { println!("{:?}", y) }
+```
 
 ## Configuration