Finalize needless_borrowed_ref lint doc.

Make sure the needless_borrowed_ref.stderr in examples is up to date
too.

clippy_lints/src/needless_borrowed_ref.rs

@@ -3,25 +3,33 @@
 //! This lint is **warn** by default
 
 use rustc::lint::*;
-<<<<<<< HEAD
-use rustc::hir::{MutImmutable, Pat, PatKind, BindingAnnotation};
-=======
-use rustc::hir::{MutImmutable, Pat, PatKind};
-<<<<<<< HEAD
->>>>>>> e30bf721... Improve needless_borrowed_ref and add suggestion to it.
+use rustc::hir::{MutImmutable, Pat, PatKind, BindByRef};
 use rustc::ty;
-=======
->>>>>>> 4ae45c87... Improve needless_borrowed_ref lint: remove the hand rolled span part.
 use utils::{span_lint_and_then, in_macro, snippet};
-use rustc::hir::BindingMode::BindByRef;
 
 /// **What it does:** Checks for useless borrowed references.
 ///
-/// **Why is this bad?** It is completely useless and make the code look more
-/// complex than it
+/// **Why is this bad?** It is mostly useless and make the code look more complex than it
 /// actually is.
 ///
-/// **Known problems:** None.
+/// **Known problems:** It seems that the `&ref` pattern is sometimes useful.
+/// For instance in the following snippet:
+/// ```rust
+/// enum Animal {
+///     Cat(u64),
+///     Dog(u64),
+/// }
+///
+/// fn foo(a: &Animal, b: &Animal) {
+///     match (a, b) {
+///         (&Animal::Cat(v), k) | (k, &Animal::Cat(v)) => (), // lifetime mismatch error
+///         (&Animal::Dog(ref c), &Animal::Dog(_)) => ()
+///     }
+/// }
+/// ```
+/// There is a lifetime mismatch error for `k` (indeed a and b have distinct lifetime).
+/// This can be fixed by using the `&ref` pattern.
+/// However, the code can also be fixed by much cleaner ways
 ///
 /// **Example:**
 /// ```rust
@@ -75,3 +83,4 @@ impl<'a, 'tcx> LateLintPass<'a, 'tcx> for NeedlessBorrowedRef {
         }}
     }
 }
+

clippy_tests/examples/needless_borrowed_ref.stderr

@@ -1,5 +1,5 @@
 error: this pattern takes a reference on something that is being de-referenced
- --> examples/needless_borrowed_ref.rs:8:34
+ --> needless_borrowed_ref.rs:8:34
   |
 8 |     let _ = v.iter_mut().filter(|&ref a| a.is_empty());
   |                                  ^^^^^^ help: try removing the `&ref` part and just keep `a`
@@ -8,30 +8,27 @@ error: this pattern takes a reference on something that is being de-referenced
   = help: for further information visit https://github.com/Manishearth/rust-clippy/wiki#needless_borrowed_reference
 
 error: this pattern takes a reference on something that is being de-referenced
-  --> examples/needless_borrowed_ref.rs:13:17
+  --> needless_borrowed_ref.rs:13:17
    |
 13 |     if let Some(&ref v) = thingy {
    |                 ^^^^^^ help: try removing the `&ref` part and just keep `v`
    |
-   = note: `-D needless-borrowed-reference` implied by `-D warnings`
    = help: for further information visit https://github.com/Manishearth/rust-clippy/wiki#needless_borrowed_reference
 
 error: this pattern takes a reference on something that is being de-referenced
-  --> examples/needless_borrowed_ref.rs:42:27
+  --> needless_borrowed_ref.rs:42:27
    |
 42 |         (&Animal::Cat(v), &ref k) | (&ref k, &Animal::Cat(v)) => (), // lifetime mismatch error if there is no '&ref'
    |                           ^^^^^^ help: try removing the `&ref` part and just keep `k`
    |
-   = note: `-D needless-borrowed-reference` implied by `-D warnings`
    = help: for further information visit https://github.com/Manishearth/rust-clippy/wiki#needless_borrowed_reference
 
 error: this pattern takes a reference on something that is being de-referenced
-  --> examples/needless_borrowed_ref.rs:42:38
+  --> needless_borrowed_ref.rs:42:38
    |
 42 |         (&Animal::Cat(v), &ref k) | (&ref k, &Animal::Cat(v)) => (), // lifetime mismatch error if there is no '&ref'
    |                                      ^^^^^^ help: try removing the `&ref` part and just keep `k`
    |
-   = note: `-D needless-borrowed-reference` implied by `-D warnings`
    = help: for further information visit https://github.com/Manishearth/rust-clippy/wiki#needless_borrowed_reference
 
 error: aborting due to previous error(s)