Merge pull request #2612 from phansch/document_how_to_use_the_author_lint

Document the author lint

Author: oli-obk

CONTRIBUTING.md

@@ -51,6 +51,44 @@ to lint-writing, though it does get into advanced stuff. Most lints consist of a
 `LintPass` with one or more of its default methods overridden. See the existing lints for examples
 of this.
 
+
+#### Author lint
+
+There is also the internal `author` lint to generate clippy code that detects the offending pattern. It does not work for all of the Rust syntax, but can give a good starting point.
+
+Create a new UI test with the pattern you want to match:
+
+```rust
+// ./tests/ui/my_lint.rs
+
+// The custom_attribute needs to be enabled for the author lint to work
+#![feature(plugin, custom_attribute)]
+
+fn main() {
+    #[clippy(author)]
+    let arr: [i32; 1] = [7]; // Replace line with the code you want to match
+}
+```
+
+Now you run `TESTNAME=ui/my_lint cargo test --test compile-test` to produce
+the file with the generated code:
+
+```rust
+// ./tests/ui/my_lint.stdout
+
+if_chain! {
+    if let Expr_::ExprArray(ref elements) = stmt.node;
+    if elements.len() == 1;
+    if let Expr_::ExprLit(ref lit) = elements[0].node;
+    if let LitKind::Int(7, _) = lit.node;
+    then {
+        // report your lint here
+    }
+}
+```
+
+#### Documentation
+
 Please document your lint with a doc comment akin to the following:
 
 ```rust
@@ -71,6 +109,8 @@ Please document your lint with a doc comment akin to the following:
 /// ```
 ```
 
+Once your lint is merged it will show up in the [lint list](https://rust-lang-nursery.github.io/rust-clippy/master/index.html)
+
 ### Running test suite
 
 Clippy uses UI tests. UI tests check that the output of the compiler is exactly as expected.

clippy_lints/src/utils/author.rs

@@ -14,6 +14,7 @@ use std::collections::HashMap;
 ///
 /// **Example:**
 /// ```rust
+/// // ./tests/ui/my_lint.rs
 /// fn foo() {
 ///     // detect the following pattern
 ///     #[clippy(author)]
@@ -24,9 +25,11 @@ use std::collections::HashMap;
 /// }
 /// ```
 ///
-/// prints
+/// Running `TESTNAME=ui/my_lint cargo test --test compile-test` will produce
+/// a `./tests/ui/new_lint.stdout` file with the generated code:
 ///
-/// ```
+/// ```rust
+/// // ./tests/ui/new_lint.stdout
 /// if_chain!{
 ///     if let Expr_::ExprIf(ref cond, ref then, None) = item.node,
 ///     if let Expr_::ExprBinary(BinOp::Eq, ref left, ref right) = cond.node,