1 files changed, 47 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/await_holding_refcell_ref.txt b/src/tools/clippy/src/docs/await_holding_refcell_ref.txt
new file mode 100644
index 000000000..226a261b9
--- /dev/null
+++ b/src/tools/clippy/src/docs/await_holding_refcell_ref.txt
@@ -0,0 +1,47 @@
+### What it does
+Checks for calls to await while holding a `RefCell` `Ref` or `RefMut`.
+
+### Why is this bad?
+`RefCell` refs only check for exclusive mutable access
+at runtime. Holding onto a `RefCell` ref across an `await` suspension point
+risks panics from a mutable ref shared while other refs are outstanding.
+
+### Known problems
+Will report false positive for explicitly dropped refs
+([#6353](https://github.com/rust-lang/rust-clippy/issues/6353)). A workaround for this is
+to wrap the `.borrow[_mut]()` call in a block instead of explicitly dropping the ref.
+
+### Example
+```
+async fn foo(x: &RefCell<u32>) {
+  let mut y = x.borrow_mut();
+  *y += 1;
+  baz().await;
+}
+
+async fn bar(x: &RefCell<u32>) {
+  let mut y = x.borrow_mut();
+  *y += 1;
+  drop(y); // explicit drop
+  baz().await;
+}
+```
+
+Use instead:
+```
+async fn foo(x: &RefCell<u32>) {
+  {
+     let mut y = x.borrow_mut();
+     *y += 1;
+  }
+  baz().await;
+}
+
+async fn bar(x: &RefCell<u32>) {
+  {
+    let mut y = x.borrow_mut();
+    *y += 1;
+  } // y dropped here at end of scope
+  baz().await;
+}
+```
+\ No newline at end of file