From 50611331b46a408f8259839c5bceaf9284985c74 Mon Sep 17 00:00:00 2001
From: Ricardo Signes <rjbs@cpan.org>
Date: Sun, 25 Oct 2015 15:58:50 -0400
Subject: [PATCH] reformat the docs for hidden code in rust sections

As displayed before this commit, I found the book confusing in its
explanation of `#`-led comments in `rust` blocks.  Possibly the
biggest confusion was because the many-dashes construct does not
become an HR element in the Markdown translator used, so things were
not being properly set off.

This change should more clearly show the as-rendered content as
rendered, and the as-coded content as code.
---
 src/doc/trpl/documentation.md | 72 +++++++++++++++++------------------
 1 file changed, 35 insertions(+), 37 deletions(-)

diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md
index 1b4a2be96b5fe..67964b9a0031a 100644
--- a/src/doc/trpl/documentation.md
+++ b/src/doc/trpl/documentation.md
@@ -269,51 +269,21 @@ documentation comment, I need to add a little function definition below
 it. At the same time, it's just there to satisfy the compiler, so hiding
 it makes the example more clear. You can use this technique to explain
 longer examples in detail, while still preserving the testability of your
-documentation. For example, this code:
-
-```rust
-let x = 5;
-let y = 6;
-println!("{}", x + y);
-```
-
-Here's an explanation, rendered:
-
--------------------------------------------------------------------------------
+documentation.
 
-First, we set `x` to five:
+For example, imagine that we wanted to document this code:
 
 ```rust
 let x = 5;
-# let y = 6;
-# println!("{}", x + y);
-```
-
-Next, we set `y` to six:
-
-```rust
-# let x = 5;
 let y = 6;
-# println!("{}", x + y);
-```
-
-Finally, we print the sum of `x` and `y`:
-
-```rust
-# let x = 5;
-# let y = 6;
 println!("{}", x + y);
 ```
 
--------------------------------------------------------------------------------
-
-Here's the same explanation, in raw text:
-
--------------------------------------------------------------------------------
+We might want the documentation to end up looking like this:
 
 > First, we set `x` to five:
 >
-> ```text
+> ```rust
 > let x = 5;
 > # let y = 6;
 > # println!("{}", x + y);
@@ -321,7 +291,7 @@ Here's the same explanation, in raw text:
 >
 > Next, we set `y` to six:
 >
-> ```text
+> ```rust
 > # let x = 5;
 > let y = 6;
 > # println!("{}", x + y);
@@ -329,13 +299,41 @@ Here's the same explanation, in raw text:
 >
 > Finally, we print the sum of `x` and `y`:
 >
-> ```text
+> ```rust
 > # let x = 5;
 > # let y = 6;
 > println!("{}", x + y);
 > ```
 
--------------------------------------------------------------------------------
+To keep each code block testable, we want the whole program in each block, but
+we don't want the reader to see every line every time.  Here's what we put in
+our source code:
+
+```text
+    First, we set `x` to five:
+
+    ```text
+    let x = 5;
+    # let y = 6;
+    # println!("{}", x + y);
+    ```
+
+    Next, we set `y` to six:
+
+    ```text
+    # let x = 5;
+    let y = 6;
+    # println!("{}", x + y);
+    ```
+
+    Finally, we print the sum of `x` and `y`:
+
+    ```text
+    # let x = 5;
+    # let y = 6;
+    println!("{}", x + y);
+    ```
+```
 
 By repeating all parts of the example, you can ensure that your example still
 compiles, while only showing the parts that are relevant to that part of your