1 files changed, 32 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/linkedlist.txt b/src/tools/clippy/src/docs/linkedlist.txt
new file mode 100644
index 000000000..986ff1369
--- /dev/null
+++ b/src/tools/clippy/src/docs/linkedlist.txt
@@ -0,0 +1,32 @@
+### What it does
+Checks for usage of any `LinkedList`, suggesting to use a
+`Vec` or a `VecDeque` (formerly called `RingBuf`).
+
+### Why is this bad?
+Gankro says:
+
+> The TL;DR of `LinkedList` is that it's built on a massive amount of
+pointers and indirection.
+> It wastes memory, it has terrible cache locality, and is all-around slow.
+`RingBuf`, while
+> "only" amortized for push/pop, should be faster in the general case for
+almost every possible
+> workload, and isn't even amortized at all if you can predict the capacity
+you need.
+>
+> `LinkedList`s are only really good if you're doing a lot of merging or
+splitting of lists.
+> This is because they can just mangle some pointers instead of actually
+copying the data. Even
+> if you're doing a lot of insertion in the middle of the list, `RingBuf`
+can still be better
+> because of how expensive it is to seek to the middle of a `LinkedList`.
+
+### Known problems
+False positives – the instances where using a
+`LinkedList` makes sense are few and far between, but they can still happen.
+
+### Example
+```
+let x: LinkedList<usize> = LinkedList::new();
+```
+\ No newline at end of file