Expanded lint documentation

clippy_lints/src/pattern_type_mismatch.rs

@@ -14,6 +14,22 @@ declare_clippy_lint! {
     /// **What it does:** Checks for patterns that aren't exact representations of the types
     /// they are applied to.
     ///
+    /// To satisfy this lint, you will have to adjust either the expression that is matched
+    /// against or the pattern itself, as well as the bindings that are introduced by the
+    /// adjusted patterns. For matching you will have to either dereference the expression
+    /// with the `*` operator, or amend the patterns to explicitly match against `&<pattern>`
+    /// or `&mut <pattern>` depending on the reference mutability. For the bindings you need
+    /// to use the inverse. You can leave them as plain bindings if you wish for the value
+    /// to be copied, but you must use `ref mut <variable>` or `ref <variable>` to construct
+    /// a reference into the matched structure.
+    ///
+    /// If you are looking for a way to learn about ownership semantics in more detail, it
+    /// is recommended to look at IDE options available to you to highlight types, lifetimes
+    /// and reference semantics in your code. The available tooling would expose these things
+    /// in a general way even outside of the various pattern matching mechanics. Of course
+    /// this lint can still be used to highlight areas of interest and ensure a good understanding
+    /// of ownership semantics.
+    ///
     /// **Why is this bad?** It isn't bad in general. But in some contexts it can be desirable
     /// because it increases ownership hints in the code, and will guard against some changes
     /// in ownership.
@@ -22,6 +38,10 @@ declare_clippy_lint! {
     ///
     /// **Example:**
     ///
+    /// This example shows the basic adjustments necessary to satisfy the lint. Note how
+    /// the matched expression is explicitly dereferenced with `*` and the `inner` variable
+    /// is bound to a shared borrow via `ref inner`.
+    ///
     /// ```rust,ignore
     /// // Bad
     /// let value = &Some(Box::new(23));
@@ -37,6 +57,25 @@ declare_clippy_lint! {
     ///     None => println!("none"),
     /// }
     /// ```
+    ///
+    /// The following example demonstrates one of the advantages of the more verbose style.
+    /// Note how the second version uses `ref mut a` to explicitly declare `a` a shared mutable
+    /// borrow, while `b` is simply taken by value. This ensures that the loop body cannot
+    /// accidentally modify the wrong part of the structure.
+    ///
+    /// ```rust,ignore
+    /// // Bad
+    /// let mut values = vec![(2, 3), (3, 4)];
+    /// for (a, b) in &mut values {
+    ///     *a += *b;
+    /// }
+    ///
+    /// // Good
+    /// let mut values = vec![(2, 3), (3, 4)];
+    /// for &mut (ref mut a, b) in &mut values {
+    ///     *a += b;
+    /// }
+    /// ```
     pub PATTERN_TYPE_MISMATCH,
     restriction,
     "type of pattern does not match the expression type"