auto merge of #11567 : divtxt/rust/master, r=cmr

I found the boxes diagram in the tutorial misleading about how the enum worked.

The current diagram makes it seem that there is a separate Cons struct when there is only one type of struct for the  List type, and Nil is drawn almost as if it's not consuming memory.

I'm aware of the optimization that happens for this enum which takes advantage of the fact that pointer cannot be null but this is an implementation detail and not the only one that applies here.  I can add a note below the diagram mentioning this if you like.

1 files changed, 9 insertions, 4 deletions

diff --git a/doc/tutorial.md b/doc/tutorial.md
index fd92a4cc080..057944484ba 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -1020,10 +1020,15 @@ being destroyed along with the owner. Since the `list` variable above is
 immutable, the whole list is immutable. The memory allocation itself is the
 box, while the owner holds onto a pointer to it:
 
-      Cons cell        Cons cell        Cons cell
-    +-----------+    +-----+-----+    +-----+-----+
-    |  1  |  ~  | -> |  2  |  ~  | -> |  3  |  ~  | -> Nil
-    +-----------+    +-----+-----+    +-----+-----+
+              List box             List box           List box            List box
+            +--------------+    +--------------+    +--------------+    +--------------+
+    list -> | Cons | 1 | ~ | -> | Cons | 2 | ~ | -> | Cons | 3 | ~ | -> | Nil          |
+            +--------------+    +--------------+    +--------------+    +--------------+
+
+> Note: the above diagram shows the logical contents of the enum. The actual
+> memory layout of the enum may vary. For example, for the `List` enum shown
+> above, Rust guarantees that there will be no enum tag field in the actual
+> structure. See the language reference for more details.
 
 An owned box is a common example of a type with a destructor. The allocated
 memory is cleaned up when the box is destroyed.