From 9f338e18afd865e776d8f8cd7c763572a9a03ddf Mon Sep 17 00:00:00 2001
From: Ivan Tham <pickfire@riseup.net>
Date: Sat, 5 Dec 2020 10:21:54 +0800
Subject: [PATCH] Add more details explaning the Vec visualization

Suggested by oli-obk
---
 library/alloc/src/vec/mod.rs | 42 +++++++++++++++++++-----------------
 1 file changed, 22 insertions(+), 20 deletions(-)

diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index 88cdf588e3566..e09c3e5d23b03 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -253,26 +253,6 @@ mod spec_extend;
 /// can be slow. For this reason, it is recommended to use [`Vec::with_capacity`]
 /// whenever possible to specify how big the vector is expected to get.
 ///
-/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be
-/// visualized as:
-///
-/// ```text
-/// Stack       ptr      len  capacity
-/// /Heap  +--------+--------+--------+
-///        | 0x0123 |      2 |      4 |
-///        +--------+--------+--------+
-///             |
-///             v
-/// Heap   +--------+--------+--------+--------+
-///        |    'a' |    'b' | uninit | uninit |
-///        +--------+--------+--------+--------+
-/// ```
-///
-/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`].
-/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory 
-///   layout (including the order of fields). See [the section about 
-///   guarantees](#guarantees).
-///
 /// # Guarantees
 ///
 /// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees
@@ -305,6 +285,28 @@ mod spec_extend;
 /// you would see if you coerced it to a slice), followed by [`capacity`]` -
 /// `[`len`] logically uninitialized, contiguous elements.
 ///
+/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be
+/// visualized as below. The top part is the `Vec` struct, it contains a
+/// pointer to the head of the allocation in the heap, length and capacity.
+/// The bottom part is the allocation on the heap, a contiguous memory block.
+///
+/// ```text
+///             ptr      len  capacity
+///        +--------+--------+--------+
+///        | 0x0123 |      2 |      4 |
+///        +--------+--------+--------+
+///             |
+///             v
+/// Heap   +--------+--------+--------+--------+
+///        |    'a' |    'b' | uninit | uninit |
+///        +--------+--------+--------+--------+
+/// ```
+///
+/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`].
+/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory
+///   layout (including the order of fields). See [the section about
+///   guarantees](#guarantees).
+///
 /// `Vec` will never perform a "small optimization" where elements are actually
 /// stored on the stack for two reasons:
 ///