Rollup merge of #24629 - steveklabnik:gh24511, r=alexcrichton

Without the `box` keyword, one of these two reasons is not correct, so
let's just eliminate this section and elaborate on the reason for the
legit use case inline.

Fixes #24511

1 files changed, 13 insertions, 8 deletions

diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index 4468e425a85..009266c3d2c 100644
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -10,14 +10,9 @@
 
 //! A pointer type for heap allocation.
 //!
-//! `Box<T>`, casually referred to as a 'box', provides the simplest form of
-//! heap allocation in Rust. Boxes provide ownership for this allocation, and
-//! drop their contents when they go out of scope.
-//!
-//! Boxes are useful in two situations: recursive data structures, and
-//! occasionally when returning data. [The Pointer chapter of the
-//! Book](../../../book/pointers.html#best-practices-1) explains these cases in
-//! detail.
+//! `Box<T>`, casually referred to as a 'box', provides the simplest form of heap allocation in
+//! Rust. Boxes provide ownership for this allocation, and drop their contents when they go out of
+//! scope.
 //!
 //! # Examples
 //!
@@ -43,6 +38,16 @@
 //! ```
 //!
 //! This will print `Cons(1, Box(Cons(2, Box(Nil))))`.
+//!
+//! Recursive structures must be boxed, because if the definition of `Cons` looked like this:
+//!
+//! ```rust,ignore
+//! Cons(T, List<T>),
+//! ```
+//!
+//! It wouldn't work. This is because the size of a `List` depends on how many elements are in the
+//! list, and so we don't know how much memory to allocate for a `Cons`. By introducing a `Box`,
+//! which has a defined size, we know how big `Cons` needs to be.
 
 #![stable(feature = "rust1", since = "1.0.0")]