1 files changed, 27 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/rc_buffer.txt b/src/tools/clippy/src/docs/rc_buffer.txt
new file mode 100644
index 000000000..82ac58eeb
--- /dev/null
+++ b/src/tools/clippy/src/docs/rc_buffer.txt
@@ -0,0 +1,27 @@
+### What it does
+Checks for `Rc<T>` and `Arc<T>` when `T` is a mutable buffer type such as `String` or `Vec`.
+
+### Why is this bad?
+Expressions such as `Rc<String>` usually have no advantage over `Rc<str>`, since
+it is larger and involves an extra level of indirection, and doesn't implement `Borrow<str>`.
+
+While mutating a buffer type would still be possible with `Rc::get_mut()`, it only
+works if there are no additional references yet, which usually defeats the purpose of
+enclosing it in a shared ownership type. Instead, additionally wrapping the inner
+type with an interior mutable container (such as `RefCell` or `Mutex`) would normally
+be used.
+
+### Known problems
+This pattern can be desirable to avoid the overhead of a `RefCell` or `Mutex` for
+cases where mutation only happens before there are any additional references.
+
+### Example
+```
+fn foo(interned: Rc<String>) { ... }
+```
+
+Better:
+
+```
+fn foo(interned: Rc<str>) { ... }
+```
+\ No newline at end of file