Rollup merge of #38297 - matklad:linked-lists-are-not-cool, r=GuillaumeGomez

Advertise Vec in LinkedList docs

r? @steveklabnik

Hi! We already [advise](https://doc.rust-lang.org/std/collections/#use-a-linkedlist-when) to use `Vec` instead of `LinkedList` in the top-level collections documentation. But I think it may be missed by someone who just directly finds `LinkedList`.

What do you feel about advertising `Vec` directly in `LinkedList` docs as well?

1 files changed, 17 insertions, 3 deletions

diff --git a/src/libcollections/linked_list.rs b/src/libcollections/linked_list.rs
index e8c2e0b5902..31085509088 100644
--- a/src/libcollections/linked_list.rs
+++ b/src/libcollections/linked_list.rs
@@ -10,8 +10,15 @@
 
 //! A doubly-linked list with owned nodes.
 //!
-//! The `LinkedList` allows pushing and popping elements at either end and is thus
-//! efficiently usable as a double-ended queue.
+//! The `LinkedList` allows pushing and popping elements at either end
+//! in constant time.
+//!
+//! Almost always it is better to use `Vec` or [`VecDeque`] instead of
+//! [`LinkedList`]. In general, array-based containers are faster,
+//! more memory efficient and make better use of CPU cache.
+//!
+//! [`LinkedList`]: ../linked_list/struct.LinkedList.html
+//! [`VecDeque`]: ../vec_deque/struct.VecDeque.html
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -27,7 +34,14 @@ use core::ptr::{self, Shared};
 
 use super::SpecExtend;
 
-/// A doubly-linked list.
+/// A doubly-linked list with owned nodes.
+///
+/// The `LinkedList` allows pushing and popping elements at either end
+/// in constant time.
+///
+/// Almost always it is better to use `Vec` or `VecDeque` instead of
+/// `LinkedList`. In general, array-based containers are faster,
+/// more memory efficient and make better use of CPU cache.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct LinkedList<T> {
     head: Option<Shared<Node<T>>>,