1 files changed, 43 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/significant_drop_in_scrutinee.txt b/src/tools/clippy/src/docs/significant_drop_in_scrutinee.txt
new file mode 100644
index 000000000..f869def0d
--- /dev/null
+++ b/src/tools/clippy/src/docs/significant_drop_in_scrutinee.txt
@@ -0,0 +1,43 @@
+### What it does
+Check for temporaries returned from function calls in a match scrutinee that have the
+`clippy::has_significant_drop` attribute.
+
+### Why is this bad?
+The `clippy::has_significant_drop` attribute can be added to types whose Drop impls have
+an important side-effect, such as unlocking a mutex, making it important for users to be
+able to accurately understand their lifetimes. When a temporary is returned in a function
+call in a match scrutinee, its lifetime lasts until the end of the match block, which may
+be surprising.
+
+For `Mutex`es this can lead to a deadlock. This happens when the match scrutinee uses a
+function call that returns a `MutexGuard` and then tries to lock again in one of the match
+arms. In that case the `MutexGuard` in the scrutinee will not be dropped until the end of
+the match block and thus will not unlock.
+
+### Example
+```
+let mutex = Mutex::new(State {});
+
+match mutex.lock().unwrap().foo() {
+    true => {
+        mutex.lock().unwrap().bar(); // Deadlock!
+    }
+    false => {}
+};
+
+println!("All done!");
+```
+Use instead:
+```
+let mutex = Mutex::new(State {});
+
+let is_foo = mutex.lock().unwrap().foo();
+match is_foo {
+    true => {
+        mutex.lock().unwrap().bar();
+    }
+    false => {}
+};
+
+println!("All done!");
+```
+\ No newline at end of file