1 files changed, 40 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/borrow_interior_mutable_const.txt b/src/tools/clippy/src/docs/borrow_interior_mutable_const.txt
new file mode 100644
index 000000000..e55b6a77e
--- /dev/null
+++ b/src/tools/clippy/src/docs/borrow_interior_mutable_const.txt
@@ -0,0 +1,40 @@
+### What it does
+Checks if `const` items which is interior mutable (e.g.,
+contains a `Cell`, `Mutex`, `AtomicXxxx`, etc.) has been borrowed directly.
+
+### Why is this bad?
+Consts are copied everywhere they are referenced, i.e.,
+every time you refer to the const a fresh instance of the `Cell` or `Mutex`
+or `AtomicXxxx` will be created, which defeats the whole purpose of using
+these types in the first place.
+
+The `const` value should be stored inside a `static` item.
+
+### Known problems
+When an enum has variants with interior mutability, use of its non
+interior mutable variants can generate false positives. See issue
+[#3962](https://github.com/rust-lang/rust-clippy/issues/3962)
+
+Types that have underlying or potential interior mutability trigger the lint whether
+the interior mutable field is used or not. See issues
+[#5812](https://github.com/rust-lang/rust-clippy/issues/5812) and
+[#3825](https://github.com/rust-lang/rust-clippy/issues/3825)
+
+### Example
+```
+use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
+const CONST_ATOM: AtomicUsize = AtomicUsize::new(12);
+
+CONST_ATOM.store(6, SeqCst); // the content of the atomic is unchanged
+assert_eq!(CONST_ATOM.load(SeqCst), 12); // because the CONST_ATOM in these lines are distinct
+```
+
+Use instead:
+```
+use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
+const CONST_ATOM: AtomicUsize = AtomicUsize::new(12);
+
+static STATIC_ATOM: AtomicUsize = CONST_ATOM;
+STATIC_ATOM.store(9, SeqCst);
+assert_eq!(STATIC_ATOM.load(SeqCst), 9); // use a `static` item to refer to the same instance
+```
+\ No newline at end of file