1 files changed, 64 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/pattern_type_mismatch.txt b/src/tools/clippy/src/docs/pattern_type_mismatch.txt
new file mode 100644
index 000000000..64da881d5
--- /dev/null
+++ b/src/tools/clippy/src/docs/pattern_type_mismatch.txt
@@ -0,0 +1,64 @@
+### 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.
+
+### 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`.
+
+```
+// Bad
+let value = &Some(Box::new(23));
+match value {
+    Some(inner) => println!("{}", inner),
+    None => println!("none"),
+}
+
+// Good
+let value = &Some(Box::new(23));
+match *value {
+    Some(ref inner) => println!("{}", inner),
+    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.
+
+```
+// 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;
+}
+```
+\ No newline at end of file