Clarified the details of a borrowing example.

Had a discussion at https://www.reddit.com/r/rust/comments/488mjv/borrowing_or_returning_ownership/ about how an example could be worded more clearly and tried to take my recommendation and expand upon it with further information provided in the post.

diff --git a/src/doc/book/references-and-borrowing.md b/src/doc/book/references-and-borrowing.md
index e7faf174600a9381b040c6c03d9deba9476f7774..0a4e09ed00ab6c48950020051d954115bd463b70 100644 (file)
--- a/src/doc/book/references-and-borrowing.md
+++ b/src/doc/book/references-and-borrowing.md
@@ -211,9 +211,10 @@ fn main() {
 ```
 
 In other words, the mutable borrow is held through the rest of our example. What
-we want is for the mutable borrow to end _before_ we try to call `println!` and
-make an immutable borrow. In Rust, borrowing is tied to the scope that the
-borrow is valid for. And our scopes look like this:
+we want is for the mutable borrow by `y` to end so that the resource can be
+returned to the owner, `x`. `x` can then provide a mutable borrow to `println!`.
+In Rust, borrowing is tied to the scope that the borrow is valid for. And our
+scopes look like this:
 
 ```rust,ignore
 let mut x = 5;
@@ -378,4 +379,3 @@ statement 1 at 3:14
 
 In the above example, `y` is declared before `x`, meaning that `y` lives longer
 than `x`, which is not allowed.
-