Auto merge of #37755 - polo-language:doc-punct, r=GuillaumeGomez

Improved punctuation, capitalization, and sentence structure of code snippet comments

r? @GuillaumeGomez

41 files changed, 184 insertions, 183 deletions

diff --git a/src/doc/book/associated-types.md b/src/doc/book/associated-types.md
index 0998a88c4d2..f416e600415 100644
--- a/src/doc/book/associated-types.md
+++ b/src/doc/book/associated-types.md
@@ -11,7 +11,7 @@ this:
 trait Graph<N, E> {
     fn has_edge(&self, &N, &N) -> bool;
     fn edges(&self, &N) -> Vec<E>;
-    // etc
+    // Etc.
 }
 ```
 
@@ -36,7 +36,7 @@ trait Graph {
 
     fn has_edge(&self, &Self::N, &Self::N) -> bool;
     fn edges(&self, &Self::N) -> Vec<Self::E>;
-    // etc
+    // Etc.
 }
 ```
 
diff --git a/src/doc/book/benchmark-tests.md b/src/doc/book/benchmark-tests.md
index 797ec94774d..e054736eb30 100644
--- a/src/doc/book/benchmark-tests.md
+++ b/src/doc/book/benchmark-tests.md
@@ -110,7 +110,7 @@ computation entirely. This could be done for the example above by adjusting the
 # struct X;
 # impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
 b.iter(|| {
-    // note lack of `;` (could also use an explicit `return`).
+    // Note lack of `;` (could also use an explicit `return`).
     (0..1000).fold(0, |old, new| old ^ new)
 });
 ```
diff --git a/src/doc/book/box-syntax-and-patterns.md b/src/doc/book/box-syntax-and-patterns.md
index 8d83b64d683..cbf65dfa9ba 100644
--- a/src/doc/book/box-syntax-and-patterns.md
+++ b/src/doc/book/box-syntax-and-patterns.md
@@ -38,7 +38,7 @@ so as to avoid copying a large data structure. For example:
 struct BigStruct {
     one: i32,
     two: i32,
-    // etc
+    // Etc.
     one_hundred: i32,
 }
 
@@ -68,7 +68,7 @@ This is an antipattern in Rust. Instead, write this:
 struct BigStruct {
     one: i32,
     two: i32,
-    // etc
+    // Etc.
     one_hundred: i32,
 }
 
diff --git a/src/doc/book/casting-between-types.md b/src/doc/book/casting-between-types.md
index a101f397c37..296384ab6ef 100644
--- a/src/doc/book/casting-between-types.md
+++ b/src/doc/book/casting-between-types.md
@@ -106,7 +106,7 @@ from integers, and to cast between pointers to different types subject to
 some constraints. It is only unsafe to dereference the pointer:
 
 ```rust
-let a = 300 as *const char; // a pointer to location 300
+let a = 300 as *const char; // `a` is a pointer to location 300.
 let b = a as u32;
 ```
 
@@ -135,14 +135,14 @@ cast four bytes into a `u32`:
 ```rust,ignore
 let a = [0u8, 0u8, 0u8, 0u8];
 
-let b = a as u32; // four u8s makes a u32
+let b = a as u32; // Four u8s makes a u32.
 ```
 
 This errors with:
 
 ```text
 error: non-scalar cast: `[u8; 4]` as `u32`
-let b = a as u32; // four u8s makes a u32
+let b = a as u32; // Four u8s makes a u32.
         ^~~~~~~~
 ```
 
@@ -170,7 +170,7 @@ fn main() {
         let a = [0u8, 1u8, 0u8, 0u8];
         let b = mem::transmute::<[u8; 4], u32>(a);
         println!("{}", b); // 256
-        // or, more concisely:
+        // Or, more concisely:
         let c: u32 = mem::transmute(a);
         println!("{}", c); // 256
     }
diff --git a/src/doc/book/choosing-your-guarantees.md b/src/doc/book/choosing-your-guarantees.md
index d88f619260a..9dca3479d35 100644
--- a/src/doc/book/choosing-your-guarantees.md
+++ b/src/doc/book/choosing-your-guarantees.md
@@ -25,7 +25,7 @@ the following:
 ```rust
 let x = Box::new(1);
 let y = x;
-// x no longer accessible here
+// `x` is no longer accessible here.
 ```
 
 Here, the box was _moved_ into `y`. As `x` no longer owns it, the compiler will no longer allow the
@@ -291,9 +291,9 @@ the inner data (mutably), and the lock will be released when the guard goes out
 ```rust,ignore
 {
     let guard = mutex.lock();
-    // guard dereferences mutably to the inner type
+    // `guard` dereferences mutably to the inner type.
     *guard += 1;
-} // lock released when destructor runs
+} // Lock is released when destructor runs.
 ```
 
 
diff --git a/src/doc/book/closures.md b/src/doc/book/closures.md
index fa9f66d43ba..a3c7333c6be 100644
--- a/src/doc/book/closures.md
+++ b/src/doc/book/closures.md
@@ -116,7 +116,7 @@ let mut num = 5;
 {
     let plus_num = |x: i32| x + num;
 
-} // plus_num goes out of scope, borrow of num ends
+} // `plus_num` goes out of scope; borrow of `num` ends.
 
 let y = &mut num;
 ```
diff --git a/src/doc/book/comments.md b/src/doc/book/comments.md
index e7eb48dc42c..8fa397cd9a6 100644
--- a/src/doc/book/comments.md
+++ b/src/doc/book/comments.md
@@ -10,7 +10,7 @@ and *doc comments*.
 ```rust
 // Line comments are anything after ‘//’ and extend to the end of the line.
 
-let x = 5; // this is also a line comment.
+let x = 5; // This is also a line comment.
 
 // If you have a long explanation for something, you can put line comments next
 // to each other. Put a space between the // and your comment so that it’s
diff --git a/src/doc/book/compiler-plugins.md b/src/doc/book/compiler-plugins.md
index a9a81843ab1..ff29358df94 100644
--- a/src/doc/book/compiler-plugins.md
+++ b/src/doc/book/compiler-plugins.md
@@ -48,7 +48,7 @@ extern crate rustc_plugin;
 use syntax::parse::token;
 use syntax::tokenstream::TokenTree;
 use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
-use syntax::ext::build::AstBuilder;  // trait for expr_usize
+use syntax::ext::build::AstBuilder;  // A trait for expr_usize.
 use syntax::ext::quote::rt::Span;
 use rustc_plugin::Registry;
 
diff --git a/src/doc/book/concurrency.md b/src/doc/book/concurrency.md
index 41d8345b720..67d89d5484c 100644
--- a/src/doc/book/concurrency.md
+++ b/src/doc/book/concurrency.md
@@ -213,10 +213,10 @@ fn main() {
     let mut data = Rc::new(vec![1, 2, 3]);
 
     for i in 0..3 {
-        // create a new owned reference
+        // Create a new owned reference:
         let data_ref = data.clone();
 
-        // use it in a thread
+        // Use it in a thread:
         thread::spawn(move || {
             data_ref[0] += i;
         });
@@ -390,8 +390,8 @@ use std::sync::mpsc;
 fn main() {
     let data = Arc::new(Mutex::new(0));
 
-    // `tx` is the "transmitter" or "sender"
-    // `rx` is the "receiver"
+    // `tx` is the "transmitter" or "sender".
+    // `rx` is the "receiver".
     let (tx, rx) = mpsc::channel();
 
     for _ in 0..10 {
diff --git a/src/doc/book/crates-and-modules.md b/src/doc/book/crates-and-modules.md
index fcb7e0bc7ea..0e336635235 100644
--- a/src/doc/book/crates-and-modules.md
+++ b/src/doc/book/crates-and-modules.md
@@ -126,7 +126,7 @@ Instead of declaring a module like this:
 
 ```rust,ignore
 mod english {
-    // contents of our module go here
+    // Contents of our module go here.
 }
 ```
 
diff --git a/src/doc/book/custom-allocators.md b/src/doc/book/custom-allocators.md
index d69ef6cf7e8..1996305f09e 100644
--- a/src/doc/book/custom-allocators.md
+++ b/src/doc/book/custom-allocators.md
@@ -41,7 +41,7 @@ which allocator is in use is done simply by linking to the desired allocator:
 extern crate alloc_system;
 
 fn main() {
-    let a = Box::new(4); // allocates from the system allocator
+    let a = Box::new(4); // Allocates from the system allocator.
     println!("{}", a);
 }
 ```
@@ -57,7 +57,7 @@ uses jemalloc by default one would write:
 extern crate alloc_jemalloc;
 
 pub fn foo() {
-    let a = Box::new(4); // allocates from jemalloc
+    let a = Box::new(4); // Allocates from jemalloc.
     println!("{}", a);
 }
 # fn main() {}
@@ -72,11 +72,11 @@ crate which implements the allocator API (e.g. the same as `alloc_system` or
 annotated version of `alloc_system`
 
 ```rust,no_run
-# // only needed for rustdoc --test down below
+# // Only needed for rustdoc --test down below.
 # #![feature(lang_items)]
 // The compiler needs to be instructed that this crate is an allocator in order
 // to realize that when this is linked in another allocator like jemalloc should
-// not be linked in
+// not be linked in.
 #![feature(allocator)]
 #![allocator]
 
@@ -85,7 +85,7 @@ annotated version of `alloc_system`
 // however, can use all of libcore.
 #![no_std]
 
-// Let's give a unique name to our custom allocator
+// Let's give a unique name to our custom allocator:
 #![crate_name = "my_allocator"]
 #![crate_type = "rlib"]
 
@@ -126,7 +126,7 @@ pub extern fn __rust_reallocate(ptr: *mut u8, _old_size: usize, size: usize,
 #[no_mangle]
 pub extern fn __rust_reallocate_inplace(_ptr: *mut u8, old_size: usize,
                                         _size: usize, _align: usize) -> usize {
-    old_size // this api is not supported by libc
+    old_size // This api is not supported by libc.
 }
 
 #[no_mangle]
@@ -134,7 +134,7 @@ pub extern fn __rust_usable_size(size: usize, _align: usize) -> usize {
     size
 }
 
-# // only needed to get rustdoc to test this
+# // Only needed to get rustdoc to test this:
 # fn main() {}
 # #[lang = "panic_fmt"] fn panic_fmt() {}
 # #[lang = "eh_personality"] fn eh_personality() {}
@@ -149,7 +149,7 @@ After we compile this crate, it can be used as follows:
 extern crate my_allocator;
 
 fn main() {
-    let a = Box::new(8); // allocates memory via our custom allocator crate
+    let a = Box::new(8); // Allocates memory via our custom allocator crate.
     println!("{}", a);
 }
 ```
diff --git a/src/doc/book/deref-coercions.md b/src/doc/book/deref-coercions.md
index cabe66f5b22..864cd282d93 100644
--- a/src/doc/book/deref-coercions.md
+++ b/src/doc/book/deref-coercions.md
@@ -33,13 +33,13 @@ automatically coerce to a `&T`. Here’s an example:
 
 ```rust
 fn foo(s: &str) {
-    // borrow a string for a second
+    // Borrow a string for a second.
 }
 
-// String implements Deref<Target=str>
+// String implements Deref<Target=str>.
 let owned = "Hello".to_string();
 
-// therefore, this works:
+// Therefore, this works:
 foo(&owned);
 ```
 
@@ -55,14 +55,14 @@ type implements `Deref<Target=T>`, so this works:
 use std::rc::Rc;
 
 fn foo(s: &str) {
-    // borrow a string for a second
+    // Borrow a string for a second.
 }
 
-// String implements Deref<Target=str>
+// String implements Deref<Target=str>.
 let owned = "Hello".to_string();
 let counted = Rc::new(owned);
 
-// therefore, this works:
+// Therefore, this works:
 foo(&counted);
 ```
 
@@ -76,10 +76,10 @@ Another very common implementation provided by the standard library is:
 
 ```rust
 fn foo(s: &[i32]) {
-    // borrow a slice for a second
+    // Borrow a slice for a second.
 }
 
-// Vec<T> implements Deref<Target=[T]>
+// Vec<T> implements Deref<Target=[T]>.
 let owned = vec![1, 2, 3];
 
 foo(&owned);
diff --git a/src/doc/book/documentation.md b/src/doc/book/documentation.md
index 6292ba9aac4..f30a95b4e78 100644
--- a/src/doc/book/documentation.md
+++ b/src/doc/book/documentation.md
@@ -28,7 +28,7 @@ code. You can use documentation comments for this purpose:
 /// let five = Rc::new(5);
 /// ```
 pub fn new(value: T) -> Rc<T> {
-    // implementation goes here
+    // Implementation goes here.
 }
 ```
 
@@ -483,7 +483,7 @@ you have a module in `foo.rs`, you'll often open its code and see this:
 ```rust
 //! A module for using `foo`s.
 //!
-//! The `foo` module contains a lot of useful functionality blah blah blah
+//! The `foo` module contains a lot of useful functionality blah blah blah...
 ```
 
 ### Crate documentation
diff --git a/src/doc/book/drop.md b/src/doc/book/drop.md
index 5513523e56b..0b7ddcfbe88 100644
--- a/src/doc/book/drop.md
+++ b/src/doc/book/drop.md
@@ -18,9 +18,9 @@ impl Drop for HasDrop {
 fn main() {
     let x = HasDrop;
 
-    // do stuff
+    // Do stuff.
 
-} // x goes out of scope here
+} // `x` goes out of scope here.
 ```
 
 When `x` goes out of scope at the end of `main()`, the code for `Drop` will
diff --git a/src/doc/book/enums.md b/src/doc/book/enums.md
index 5e05b4ebbdf..790d6ff8546 100644
--- a/src/doc/book/enums.md
+++ b/src/doc/book/enums.md
@@ -51,7 +51,7 @@ possible variants:
 
 ```rust,ignore
 fn process_color_change(msg: Message) {
-    let Message::ChangeColor(r, g, b) = msg; // compile-time error
+    let Message::ChangeColor(r, g, b) = msg; // This causes a compile-time error.
 }
 ```
 
diff --git a/src/doc/book/error-handling.md b/src/doc/book/error-handling.md
index a62e1b7dfa9..0d9f49d66cb 100644
--- a/src/doc/book/error-handling.md
+++ b/src/doc/book/error-handling.md
@@ -65,7 +65,7 @@ and in most cases, the entire program aborts.) Here's an example:
 
 ```rust,should_panic
 // Guess a number between 1 and 10.
-// If it matches the number we had in mind, return true. Else, return false.
+// If it matches the number we had in mind, return `true`. Else, return `false`.
 fn guess(n: i32) -> bool {
     if n < 1 || n > 10 {
         panic!("Invalid number: {}", n);
@@ -350,7 +350,7 @@ fn file_path_ext_explicit(file_path: &str) -> Option<&str> {
 }
 
 fn file_name(file_path: &str) -> Option<&str> {
-  // implementation elided
+  // Implementation elided.
   unimplemented!()
 }
 ```
@@ -360,7 +360,7 @@ analysis, but its type doesn't quite fit...
 
 ```rust,ignore
 fn file_path_ext(file_path: &str) -> Option<&str> {
-    file_name(file_path).map(|x| extension(x)) //Compilation error
+    file_name(file_path).map(|x| extension(x)) // This causes a compilation error.
 }
 ```
 
@@ -1235,11 +1235,11 @@ use std::fs;
 use std::io;
 use std::num;
 
-// We have to jump through some hoops to actually get error values.
+// We have to jump through some hoops to actually get error values:
 let io_err: io::Error = io::Error::last_os_error();
 let parse_err: num::ParseIntError = "not a number".parse::<i32>().unwrap_err();
 
-// OK, here are the conversions.
+// OK, here are the conversions:
 let err1: Box<Error> = From::from(io_err);
 let err2: Box<Error> = From::from(parse_err);
 ```
@@ -1609,7 +1609,7 @@ fn main() {
     let data_path = &matches.free[0];
     let city: &str = &matches.free[1];
 
-    // Do stuff with information
+    // Do stuff with information.
 }
 ```
 
@@ -1747,7 +1747,7 @@ simply ignoring that row.
 use std::path::Path;
 
 struct Row {
-    // unchanged
+    // This struct remains unchanged.
 }
 
 struct PopulationCount {
@@ -1769,7 +1769,7 @@ fn search<P: AsRef<Path>>(file_path: P, city: &str) -> Vec<PopulationCount> {
     for row in rdr.decode::<Row>() {
         let row = row.unwrap();
         match row.population {
-            None => { } // skip it
+            None => { } // Skip it.
             Some(count) => if row.city == city {
                 found.push(PopulationCount {
                     city: row.city,
@@ -1825,7 +1825,7 @@ Let's try it:
 ```rust,ignore
 use std::error::Error;
 
-// The rest of the code before this is unchanged
+// The rest of the code before this is unchanged.
 
 fn search<P: AsRef<Path>>
          (file_path: P, city: &str)
@@ -1836,7 +1836,7 @@ fn search<P: AsRef<Path>>
     for row in rdr.decode::<Row>() {
         let row = try!(row);
         match row.population {
-            None => { } // skip it
+            None => { } // Skip it.
             Some(count) => if row.city == city {
                 found.push(PopulationCount {
                     city: row.city,
@@ -1957,7 +1957,7 @@ that it is generic on some type parameter `R` that satisfies
 ```rust,ignore
 use std::io;
 
-// The rest of the code before this is unchanged
+// The rest of the code before this is unchanged.
 
 fn search<P: AsRef<Path>>
          (file_path: &Option<P>, city: &str)
@@ -2070,7 +2070,7 @@ fn search<P: AsRef<Path>>
     for row in rdr.decode::<Row>() {
         let row = try!(row);
         match row.population {
-            None => { } // skip it
+            None => { } // Skip it.
             Some(count) => if row.city == city {
                 found.push(PopulationCount {
                     city: row.city,
diff --git a/src/doc/book/ffi.md b/src/doc/book/ffi.md
index cae5d3eb46a..7510cd0b3b5 100644
--- a/src/doc/book/ffi.md
+++ b/src/doc/book/ffi.md
@@ -277,7 +277,7 @@ extern {
 fn main() {
     unsafe {
         register_callback(callback);
-        trigger_callback(); // Triggers the callback
+        trigger_callback(); // Triggers the callback.
     }
 }
 ```
@@ -294,7 +294,7 @@ int32_t register_callback(rust_callback callback) {
 }
 
 void trigger_callback() {
-  cb(7); // Will call callback(7) in Rust
+  cb(7); // Will call callback(7) in Rust.
 }
 ```
 
@@ -320,13 +320,13 @@ Rust code:
 #[repr(C)]
 struct RustObject {
     a: i32,
-    // other members
+    // Other members...
 }
 
 extern "C" fn callback(target: *mut RustObject, a: i32) {
     println!("I'm called from C with value {0}", a);
     unsafe {
-        // Update the value in RustObject with the value received from the callback
+        // Update the value in RustObject with the value received from the callback:
         (*target).a = a;
     }
 }
@@ -339,7 +339,7 @@ extern {
 }
 
 fn main() {
-    // Create the object that will be referenced in the callback
+    // Create the object that will be referenced in the callback:
     let mut rust_object = Box::new(RustObject { a: 5 });
 
     unsafe {
@@ -363,7 +363,7 @@ int32_t register_callback(void* callback_target, rust_callback callback) {
 }
 
 void trigger_callback() {
-  cb(cb_target, 7); // Will call callback(&rustObject, 7) in Rust
+  cb(cb_target, 7); // Will call callback(&rustObject, 7) in Rust.
 }
 ```
 
@@ -606,7 +606,7 @@ use libc::c_int;
 
 # #[cfg(hidden)]
 extern "C" {
-    /// Register the callback.
+    /// Registers the callback.
     fn register(cb: Option<extern "C" fn(Option<extern "C" fn(c_int) -> c_int>, c_int) -> c_int>);
 }
 # unsafe fn register(_: Option<extern "C" fn(Option<extern "C" fn(c_int) -> c_int>,
diff --git a/src/doc/book/functions.md b/src/doc/book/functions.md
index b040684d05f..b453936fe00 100644
--- a/src/doc/book/functions.md
+++ b/src/doc/book/functions.md
@@ -135,7 +135,7 @@ In Rust, however, using `let` to introduce a binding is _not_ an expression. The
 following will produce a compile-time error:
 
 ```rust,ignore
-let x = (let y = 5); // expected identifier, found keyword `let`
+let x = (let y = 5); // Expected identifier, found keyword `let`.
 ```
 
 The compiler is telling us here that it was expecting to see the beginning of
@@ -151,7 +151,7 @@ other returned value would be too surprising:
 ```rust
 let mut y = 5;
 
-let x = (y = 6);  // x has the value `()`, not `6`
+let x = (y = 6);  // `x` has the value `()`, not `6`.
 ```
 
 The second kind of statement in Rust is the *expression statement*. Its
@@ -183,7 +183,7 @@ But what about early returns? Rust does have a keyword for that, `return`:
 fn foo(x: i32) -> i32 {
     return x;
 
-    // we never run this code!
+    // We never run this code!
     x + 1
 }
 ```
@@ -307,10 +307,10 @@ fn plus_one(i: i32) -> i32 {
     i + 1
 }
 
-// without type inference
+// Without type inference:
 let f: fn(i32) -> i32 = plus_one;
 
-// with type inference
+// With type inference:
 let f = plus_one;
 ```
 
diff --git a/src/doc/book/generics.md b/src/doc/book/generics.md
index 9ab601419cd..eafad6a05fc 100644
--- a/src/doc/book/generics.md
+++ b/src/doc/book/generics.md
@@ -78,7 +78,7 @@ We can write functions that take generic types with a similar syntax:
 
 ```rust
 fn takes_anything<T>(x: T) {
-    // do something with x
+    // Do something with `x`.
 }
 ```
 
diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md
index e2a23979a81..c854b7c373d 100644
--- a/src/doc/book/guessing-game.md
+++ b/src/doc/book/guessing-game.md
@@ -158,8 +158,8 @@ take a name on the left hand side of the assignment, it actually accepts a
 to use for now:
 
 ```rust
-let foo = 5; // immutable.
-let mut bar = 5; // mutable
+let foo = 5; // `foo` is immutable.
+let mut bar = 5; // `bar` is mutable.
 ```
 
 [immutable]: mutability.html
diff --git a/src/doc/book/inline-assembly.md b/src/doc/book/inline-assembly.md
index 62e196a7ccd..e531d5d7fc0 100644
--- a/src/doc/book/inline-assembly.md
+++ b/src/doc/book/inline-assembly.md
@@ -34,7 +34,7 @@ fn foo() {
     }
 }
 
-// other platforms
+// Other platforms:
 #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
 fn foo() { /* ... */ }
 
@@ -130,7 +130,7 @@ stay valid.
 # #![feature(asm)]
 # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
 # fn main() { unsafe {
-// Put the value 0x200 in eax
+// Put the value 0x200 in eax:
 asm!("mov $$0x200, %eax" : /* no outputs */ : /* no inputs */ : "eax");
 # } }
 # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
diff --git a/src/doc/book/lang-items.md b/src/doc/book/lang-items.md
index 9fb130845fb..6a08c1b6bb4 100644
--- a/src/doc/book/lang-items.md
+++ b/src/doc/book/lang-items.md
@@ -32,7 +32,7 @@ pub struct Box<T>(*mut T);
 unsafe fn allocate(size: usize, _align: usize) -> *mut u8 {
     let p = libc::malloc(size as libc::size_t) as *mut u8;
 
-    // malloc failed
+    // Check if `malloc` failed:
     if p as usize == 0 {
         abort();
     }
diff --git a/src/doc/book/lifetimes.md b/src/doc/book/lifetimes.md
index df1ee5a293c..397263c6973 100644
--- a/src/doc/book/lifetimes.md
+++ b/src/doc/book/lifetimes.md
@@ -54,13 +54,13 @@ dangling pointer or ‘use after free’, when the resource is memory. A small
 example of such a situation would be:
 
 ```rust,compile_fail
-let r;              // Introduce reference: r
+let r;              // Introduce reference: `r`.
 {
-    let i = 1;      // Introduce scoped value: i
-    r = &i;         // Store reference of i in r
-}                   // i goes out of scope and is dropped.
+    let i = 1;      // Introduce scoped value: `i`.
+    r = &i;         // Store reference of `i` in `r`.
+}                   // `i` goes out of scope and is dropped.
 
-println!("{}", r);  // r still refers to i
+println!("{}", r);  // `r` still refers to `i`.
 ```
 
 To fix this, we have to make sure that step four never happens after step
@@ -81,9 +81,9 @@ let lang = "en";
 
 let v;
 {
-    let p = format!("lang:{}=", lang);  // -+ p goes into scope
+    let p = format!("lang:{}=", lang);  // -+ `p` comes into scope.
     v = skip_prefix(line, p.as_str());  //  |
-}                                       // -+ p goes out of scope
+}                                       // -+ `p` goes out of scope.
 println!("{}", v);
 ```
 
@@ -191,7 +191,7 @@ struct Foo<'a> {
 }
 
 fn main() {
-    let y = &5; // this is the same as `let _y = 5; let y = &_y;`
+    let y = &5; // This is the same as `let _y = 5; let y = &_y;`.
     let f = Foo { x: y };
 
     println!("{}", f.x);
@@ -233,7 +233,7 @@ impl<'a> Foo<'a> {
 }
 
 fn main() {
-    let y = &5; // this is the same as `let _y = 5; let y = &_y;`
+    let y = &5; // This is the same as `let _y = 5; let y = &_y;`.
     let f = Foo { x: y };
 
     println!("x is: {}", f.x());
@@ -274,11 +274,11 @@ valid for. For example:
 
 ```rust
 fn main() {
-    let y = &5;     // -+ y goes into scope
+    let y = &5;     // -+ `y` comes into scope.
                     //  |
-    // stuff        //  |
+    // Stuff...     //  |
                     //  |
-}                   // -+ y goes out of scope
+}                   // -+ `y` goes out of scope.
 ```
 
 Adding in our `Foo`:
@@ -289,11 +289,12 @@ struct Foo<'a> {
 }
 
 fn main() {
-    let y = &5;           // -+ y goes into scope
-    let f = Foo { x: y }; // -+ f goes into scope
-    // stuff              //  |
+    let y = &5;           // -+ `y` comes into scope.
+    let f = Foo { x: y }; // -+ `f` comes into scope.
                           //  |
-}                         // -+ f and y go out of scope
+    // Stuff...           //  |
+                          //  |
+}                         // -+ `f` and `y` go out of scope.
 ```
 
 Our `f` lives within the scope of `y`, so everything works. What if it didn’t?
@@ -305,16 +306,16 @@ struct Foo<'a> {
 }
 
 fn main() {
-    let x;                    // -+ x goes into scope
+    let x;                    // -+ `x` comes into scope.
                               //  |
     {                         //  |
-        let y = &5;           // ---+ y goes into scope
-        let f = Foo { x: y }; // ---+ f goes into scope
-        x = &f.x;             //  | | error here
-    }                         // ---+ f and y go out of scope
+        let y = &5;           // ---+ `y` comes into scope.
+        let f = Foo { x: y }; // ---+ `f` comes into scope.
+        x = &f.x;             //  | | This causes an error.
+    }                         // ---+ `f` and y go out of scope.
                               //  |
     println!("{}", x);        //  |
-}                             // -+ x goes out of scope
+}                             // -+ `x` goes out of scope.
 ```
 
 Whew! As you can see here, the scopes of `f` and `y` are smaller than the scope
diff --git a/src/doc/book/loops.md b/src/doc/book/loops.md
index e4cb861d3b0..688e8c55265 100644
--- a/src/doc/book/loops.md
+++ b/src/doc/book/loops.md
@@ -202,8 +202,8 @@ of the outer loops, you can use labels to specify which loop the `break` or
 ```rust
 'outer: for x in 0..10 {
     'inner: for y in 0..10 {
-        if x % 2 == 0 { continue 'outer; } // continues the loop over x
-        if y % 2 == 0 { continue 'inner; } // continues the loop over y
+        if x % 2 == 0 { continue 'outer; } // Continues the loop over `x`.
+        if y % 2 == 0 { continue 'inner; } // Continues the loop over `y`.
         println!("x: {}, y: {}", x, y);
     }
 }
diff --git a/src/doc/book/macros.md b/src/doc/book/macros.md
index 78fe07ec1be..7f52b33948e 100644
--- a/src/doc/book/macros.md
+++ b/src/doc/book/macros.md
@@ -533,33 +533,33 @@ An example:
 ```rust
 macro_rules! m1 { () => (()) }
 
-// visible here: m1
+// Visible here: `m1`.
 
 mod foo {
-    // visible here: m1
+    // Visible here: `m1`.
 
     #[macro_export]
     macro_rules! m2 { () => (()) }
 
-    // visible here: m1, m2
+    // Visible here: `m1`, `m2`.
 }
 
-// visible here: m1
+// Visible here: `m1`.
 
 macro_rules! m3 { () => (()) }
 
-// visible here: m1, m3
+// Visible here: `m1`, `m3`.
 
 #[macro_use]
 mod bar {
-    // visible here: m1, m3
+    // Visible here: `m1`, `m3`.
 
     macro_rules! m4 { () => (()) }
 
-    // visible here: m1, m3, m4
+    // Visible here: `m1`, `m3`, `m4`.
 }
 
-// visible here: m1, m3, m4
+// Visible here: `m1`, `m3`, `m4`.
 # fn main() { }
 ```
 
@@ -644,7 +644,7 @@ macro_rules! bct {
     (1, $p:tt, $($ps:tt),* ; $($ds:tt),*)
         => (bct!($($ps),*, 1, $p ; $($ds),*));
 
-    // halt on empty data string
+    // Halt on empty data string:
     ( $($ps:tt),* ; )
         => (());
 }
@@ -694,7 +694,7 @@ Like this:
 assert!(true);
 assert_eq!(5, 3 + 2);
 
-// nope :(
+// Nope :(
 
 assert!(5 < 3);
 assert_eq!(5, 3);
diff --git a/src/doc/book/mutability.md b/src/doc/book/mutability.md
index a0a49d55e10..18017cc4a5e 100644
--- a/src/doc/book/mutability.md
+++ b/src/doc/book/mutability.md
@@ -6,7 +6,7 @@ status:
 
 ```rust,ignore
 let x = 5;
-x = 6; // error!
+x = 6; // Error!
 ```
 
 We can introduce mutability with the `mut` keyword:
@@ -14,7 +14,7 @@ We can introduce mutability with the `mut` keyword:
 ```rust
 let mut x = 5;
 
-x = 6; // no problem!
+x = 6; // No problem!
 ```
 
 This is a mutable [variable binding][vb]. When a binding is mutable, it means
@@ -136,7 +136,7 @@ some fields mutable and some immutable:
 ```rust,ignore
 struct Point {
     x: i32,
-    mut y: i32, // nope
+    mut y: i32, // Nope.
 }
 ```
 
@@ -154,7 +154,7 @@ a.x = 10;
 
 let b = Point { x: 5, y: 6};
 
-b.x = 10; // error: cannot assign to immutable field `b.x`
+b.x = 10; // Error: cannot assign to immutable field `b.x`.
 ```
 
 [struct]: structs.html
diff --git a/src/doc/book/no-stdlib.md b/src/doc/book/no-stdlib.md
index 2604ca8d4ca..a06de35c0ce 100644
--- a/src/doc/book/no-stdlib.md
+++ b/src/doc/book/no-stdlib.md
@@ -41,10 +41,10 @@ in the same format as C:
 #![feature(start)]
 #![no_std]
 
-// Pull in the system libc library for what crt0.o likely requires
+// Pull in the system libc library for what crt0.o likely requires.
 extern crate libc;
 
-// Entry point for this program
+// Entry point for this program.
 #[start]
 fn start(_argc: isize, _argv: *const *const u8) -> isize {
     0
@@ -84,10 +84,10 @@ compiler's name mangling too:
 #![no_std]
 #![no_main]
 
-// Pull in the system libc library for what crt0.o likely requires
+// Pull in the system libc library for what crt0.o likely requires.
 extern crate libc;
 
-// Entry point for this program
+// Entry point for this program.
 #[no_mangle] // ensure that this symbol is called `main` in the output
 pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
     0
diff --git a/src/doc/book/operators-and-overloading.md b/src/doc/book/operators-and-overloading.md
index 424e2cda615..78ff871046e 100644
--- a/src/doc/book/operators-and-overloading.md
+++ b/src/doc/book/operators-and-overloading.md
@@ -69,7 +69,7 @@ impl Add<i32> for Point {
     type Output = f64;
 
     fn add(self, rhs: i32) -> f64 {
-        // add an i32 to a Point and get an f64
+        // Add an i32 to a Point and get an f64.
 # 1.0
     }
 }
diff --git a/src/doc/book/ownership.md b/src/doc/book/ownership.md
index a711397b211..11eda399adc 100644
--- a/src/doc/book/ownership.md
+++ b/src/doc/book/ownership.md
@@ -107,7 +107,7 @@ try to use something after we’ve passed it as an argument:
 
 ```rust,ignore
 fn take(v: Vec<i32>) {
-    // what happens here isn’t important.
+    // What happens here isn’t important.
 }
 
 let v = vec![1, 2, 3];
@@ -264,9 +264,9 @@ Of course, if we had to hand ownership back with every function we wrote:
 
 ```rust
 fn foo(v: Vec<i32>) -> Vec<i32> {
-    // do stuff with v
+    // Do stuff with `v`.
 
-    // hand back ownership
+    // Hand back ownership.
     v
 }
 ```
@@ -275,9 +275,9 @@ This would get very tedious. It gets worse the more things we want to take owner
 
 ```rust
 fn foo(v1: Vec<i32>, v2: Vec<i32>) -> (Vec<i32>, Vec<i32>, i32) {
-    // do stuff with v1 and v2
+    // Do stuff with `v1` and `v2`.
 
-    // hand back ownership, and the result of our function
+    // Hand back ownership, and the result of our function.
     (v1, v2, 42)
 }
 
diff --git a/src/doc/book/patterns.md b/src/doc/book/patterns.md
index 910b1375476..b50fa01b8e2 100644
--- a/src/doc/book/patterns.md
+++ b/src/doc/book/patterns.md
@@ -163,7 +163,7 @@ ignore parts of a larger structure:
 
 ```rust
 fn coordinate() -> (i32, i32, i32) {
-    // generate and return some sort of triple tuple
+    // Generate and return some sort of triple tuple.
 # (1, 2, 3)
 }
 
@@ -182,7 +182,7 @@ let tuple: (u32, String) = (5, String::from("five"));
 // Here, tuple is moved, because the String moved:
 let (x, _s) = tuple;
 
-// The next line would give "error: use of partially moved value: `tuple`"
+// The next line would give "error: use of partially moved value: `tuple`".
 // println!("Tuple is: {:?}", tuple);
 
 // However,
diff --git a/src/doc/book/primitive-types.md b/src/doc/book/primitive-types.md
index ea0bdf29fcc..c4169d64ccc 100644
--- a/src/doc/book/primitive-types.md
+++ b/src/doc/book/primitive-types.md
@@ -54,9 +54,9 @@ bigger numbers.
 If a number literal has nothing to cause its type to be inferred, it defaults:
 
 ```rust
-let x = 42; // x has type i32
+let x = 42; // `x` has type `i32`.
 
-let y = 1.0; // y has type f64
+let y = 1.0; // `y` has type `f64`.
 ```
 
 Here’s a list of the different numeric types, with links to their documentation
@@ -177,8 +177,8 @@ length of the slice:
 
 ```rust
 let a = [0, 1, 2, 3, 4];
-let complete = &a[..]; // A slice containing all of the elements in a
-let middle = &a[1..4]; // A slice of a: only the elements 1, 2, and 3
+let complete = &a[..]; // A slice containing all of the elements in `a`.
+let middle = &a[1..4]; // A slice of `a`: only the elements `1`, `2`, and `3`.
 ```
 
 Slices have type `&[T]`. We’ll talk about that `T` when we cover
@@ -264,8 +264,8 @@ You can disambiguate a single-element tuple from a value in parentheses with a
 comma:
 
 ```rust
-(0,); // single-element tuple
-(0); // zero in parentheses
+(0,); // A single-element tuple.
+(0); // A zero in parentheses.
 ```
 
 ## Tuple Indexing
diff --git a/src/doc/book/raw-pointers.md b/src/doc/book/raw-pointers.md
index ae100aec3b5..2386475d15e 100644
--- a/src/doc/book/raw-pointers.md
+++ b/src/doc/book/raw-pointers.md
@@ -101,11 +101,11 @@ programmer *must* guarantee this.
 The recommended method for the conversion is:
 
 ```rust
-// explicit cast
+// Explicit cast:
 let i: u32 = 1;
 let p_imm: *const u32 = &i as *const u32;
 
-// implicit coercion
+// Implicit coercion:
 let mut m: u32 = 2;
 let p_mut: *mut u32 = &mut m;
 
diff --git a/src/doc/book/references-and-borrowing.md b/src/doc/book/references-and-borrowing.md
index 1e2f061b067..6c9c4fa7dd4 100644
--- a/src/doc/book/references-and-borrowing.md
+++ b/src/doc/book/references-and-borrowing.md
@@ -46,9 +46,9 @@ like this:
 
 ```rust
 fn foo(v1: Vec<i32>, v2: Vec<i32>) -> (Vec<i32>, Vec<i32>, i32) {
-    // do stuff with v1 and v2
+    // Do stuff with `v1` and `v2`.
 
-    // hand back ownership, and the result of our function
+    // Hand back ownership, and the result of our function.
     (v1, v2, 42)
 }
 
@@ -63,9 +63,9 @@ the first step:
 
 ```rust
 fn foo(v1: &Vec<i32>, v2: &Vec<i32>) -> i32 {
-    // do stuff with v1 and v2
+    // Do stuff with `v1` and `v2`.
 
-    // return the answer
+    // Return the answer.
     42
 }
 
@@ -74,7 +74,7 @@ let v2 = vec![1, 2, 3];
 
 let answer = foo(&v1, &v2);
 
-// we can use v1 and v2 here!
+// We can use `v1` and `v2` here!
 ```
 
 A more concrete example:
@@ -88,10 +88,10 @@ fn main() {
     // Borrow two vectors and sum them.
     // This kind of borrowing does not allow mutation through the borrowed reference.
     fn foo(v1: &Vec<i32>, v2: &Vec<i32>) -> i32 {
-        // do stuff with v1 and v2
+        // Do stuff with `v1` and `v2`.
         let s1 = sum_vec(v1);
         let s2 = sum_vec(v2);
-        // return the answer
+        // Return the answer.
         s1 + s2
     }
 
@@ -248,12 +248,12 @@ scopes look like this:
 fn main() {
     let mut x = 5;
 
-    let y = &mut x;    // -+ &mut borrow of x starts here
+    let y = &mut x;    // -+ &mut borrow of `x` starts here.
                        //  |
     *y += 1;           //  |
                        //  |
-    println!("{}", x); // -+ - try to borrow x here
-}                      // -+ &mut borrow of x ends here
+    println!("{}", x); // -+ - Try to borrow `x` here.
+}                      // -+ &mut borrow of `x` ends here.
                        
 ```
 
@@ -265,11 +265,11 @@ So when we add the curly braces:
 let mut x = 5;
 
 {
-    let y = &mut x; // -+ &mut borrow starts here
+    let y = &mut x; // -+ &mut borrow starts here.
     *y += 1;        //  |
-}                   // -+ ... and ends here
+}                   // -+ ... and ends here.
 
-println!("{}", x);  // <- try to borrow x here
+println!("{}", x);  // <- Try to borrow `x` here.
 ```
 
 There’s no problem. Our mutable borrow goes out of scope before we create an
diff --git a/src/doc/book/strings.md b/src/doc/book/strings.md
index 135778c38b5..6af15d87683 100644
--- a/src/doc/book/strings.md
+++ b/src/doc/book/strings.md
@@ -83,10 +83,10 @@ converted using `&*`.
 ```rust,no_run
 use std::net::TcpStream;
 
-TcpStream::connect("192.168.0.1:3000"); // &str parameter
+TcpStream::connect("192.168.0.1:3000"); // Parameter is of type &str.
 
 let addr_string = "192.168.0.1:3000".to_string();
-TcpStream::connect(&*addr_string); // convert addr_string to &str
+TcpStream::connect(&*addr_string); // Convert `addr_string` to &str.
 ```
 
 Viewing a `String` as a `&str` is cheap, but converting the `&str` to a
@@ -138,7 +138,7 @@ You can get something similar to an index like this:
 
 ```rust
 # let hachiko = "忠犬ハチ公";
-let dog = hachiko.chars().nth(1); // kinda like hachiko[1]
+let dog = hachiko.chars().nth(1); // Kinda like `hachiko[1]`.
 ```
 
 This emphasizes that we have to walk from the beginning of the list of `chars`.
diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md
index d6960b10b08..cfd00cf997e 100644
--- a/src/doc/book/structs.md
+++ b/src/doc/book/structs.md
@@ -82,9 +82,9 @@ fn main() {
 
     point.x = 5;
 
-    let point = point; // now immutable
+    let point = point; // `point` is now immutable.
 
-    point.y = 6; // this causes an error
+    point.y = 6; // This causes an error.
 }
 ```
 
@@ -234,10 +234,10 @@ rather than positions.
 You can define a `struct` with no members at all:
 
 ```rust
-struct Electron {} // use empty braces...
-struct Proton;     // ...or just a semicolon
+struct Electron {} // Use empty braces...
+struct Proton;     // ...or just a semicolon.
 
-// whether you declared the struct with braces or not, do the same when creating one
+// Whether you declared the struct with braces or not, do the same when creating one.
 let x = Electron {};
 let y = Proton;
 ```
diff --git a/src/doc/book/testing.md b/src/doc/book/testing.md
index ed916fd798b..0f48f579864 100644
--- a/src/doc/book/testing.md
+++ b/src/doc/book/testing.md
@@ -299,7 +299,7 @@ fn it_works() {
 #[test]
 #[ignore]
 fn expensive_test() {
-    // code that takes an hour to run
+    // Code that takes an hour to run...
 }
 ```
 
diff --git a/src/doc/book/trait-objects.md b/src/doc/book/trait-objects.md
index b1aee579aab..a0396a75fa2 100644
--- a/src/doc/book/trait-objects.md
+++ b/src/doc/book/trait-objects.md
@@ -221,8 +221,8 @@ struct FooVtable {
 // u8:
 
 fn call_method_on_u8(x: *const ()) -> String {
-    // the compiler guarantees that this function is only called
-    // with `x` pointing to a u8
+    // The compiler guarantees that this function is only called
+    // with `x` pointing to a u8.
     let byte: &u8 = unsafe { &*(x as *const u8) };
 
     byte.method()
@@ -233,7 +233,7 @@ static Foo_for_u8_vtable: FooVtable = FooVtable {
     size: 1,
     align: 1,
 
-    // cast to a function pointer
+    // Cast to a function pointer:
     method: call_method_on_u8 as fn(*const ()) -> String,
 };
 
@@ -241,8 +241,8 @@ static Foo_for_u8_vtable: FooVtable = FooVtable {
 // String:
 
 fn call_method_on_String(x: *const ()) -> String {
-    // the compiler guarantees that this function is only called
-    // with `x` pointing to a String
+    // The compiler guarantees that this function is only called
+    // with `x` pointing to a String.
     let string: &String = unsafe { &*(x as *const String) };
 
     string.method()
@@ -250,7 +250,7 @@ fn call_method_on_String(x: *const ()) -> String {
 
 static Foo_for_String_vtable: FooVtable = FooVtable {
     destructor: /* compiler magic */,
-    // values for a 64-bit computer, halve them for 32-bit ones
+    // Values for a 64-bit computer, halve them for 32-bit ones.
     size: 24,
     align: 8,
 
@@ -278,17 +278,17 @@ let x: u8 = 1;
 
 // let b: &Foo = &a;
 let b = TraitObject {
-    // store the data
+    // Store the data:
     data: &a,
-    // store the methods
+    // Store the methods:
     vtable: &Foo_for_String_vtable
 };
 
 // let y: &Foo = x;
 let y = TraitObject {
-    // store the data
+    // Store the data:
     data: &x,
-    // store the methods
+    // Store the methods:
     vtable: &Foo_for_u8_vtable
 };
 
diff --git a/src/doc/book/traits.md b/src/doc/book/traits.md
index d1166e686c7..4747869b65c 100644
--- a/src/doc/book/traits.md
+++ b/src/doc/book/traits.md
@@ -270,9 +270,9 @@ won’t have its methods:
 
 ```rust,ignore
 let mut f = std::fs::File::create("foo.txt").expect("Couldn’t create foo.txt");
-let buf = b"whatever"; // byte string literal. buf: &[u8; 8]
+let buf = b"whatever"; // buf: &[u8; 8], a byte string literal.
 let result = f.write(buf);
-# result.unwrap(); // ignore the error
+# result.unwrap(); // Ignore the error.
 ```
 
 Here’s the error:
@@ -291,7 +291,7 @@ use std::io::Write;
 let mut f = std::fs::File::create("foo.txt").expect("Couldn’t create foo.txt");
 let buf = b"whatever";
 let result = f.write(buf);
-# result.unwrap(); // ignore the error
+# result.unwrap(); // Ignore the error.
 ```
 
 This will compile without error.
@@ -413,14 +413,14 @@ impl ConvertTo<i64> for i32 {
     fn convert(&self) -> i64 { *self as i64 }
 }
 
-// can be called with T == i32
+// Can be called with T == i32.
 fn normal<T: ConvertTo<i64>>(x: &T) -> i64 {
     x.convert()
 }
 
-// can be called with T == i64
+// Can be called with T == i64.
 fn inverse<T>(x: i32) -> T
-        // this is using ConvertTo as if it were "ConvertTo<i64>"
+        // This is using ConvertTo as if it were "ConvertTo<i64>".
         where i32: ConvertTo<T> {
     x.convert()
 }
@@ -470,15 +470,15 @@ impl Foo for OverrideDefault {
 
     fn is_invalid(&self) -> bool {
         println!("Called OverrideDefault.is_invalid!");
-        true // overrides the expected value of is_invalid()
+        true // Overrides the expected value of `is_invalid()`.
     }
 }
 
 let default = UseDefault;
-assert!(!default.is_invalid()); // prints "Called UseDefault.is_valid."
+assert!(!default.is_invalid()); // Prints "Called UseDefault.is_valid."
 
 let over = OverrideDefault;
-assert!(over.is_invalid()); // prints "Called OverrideDefault.is_invalid!"
+assert!(over.is_invalid()); // Prints "Called OverrideDefault.is_invalid!"
 ```
 
 # Inheritance
diff --git a/src/doc/book/unsafe.md b/src/doc/book/unsafe.md
index 9cab586b82c..a272afa70bb 100644
--- a/src/doc/book/unsafe.md
+++ b/src/doc/book/unsafe.md
@@ -12,7 +12,7 @@ four contexts. The first one is to mark a function as unsafe:
 
 ```rust
 unsafe fn danger_will_robinson() {
-    // scary stuff
+    // Scary stuff...
 }
 ```
 
@@ -23,7 +23,7 @@ The second use of `unsafe` is an unsafe block:
 
 ```rust
 unsafe {
-    // scary stuff
+    // Scary stuff...
 }
 ```
 
diff --git a/src/doc/book/variable-bindings.md b/src/doc/book/variable-bindings.md
index 03f17371de6..54316649c71 100644
--- a/src/doc/book/variable-bindings.md
+++ b/src/doc/book/variable-bindings.md
@@ -194,7 +194,7 @@ fn main() {
         let y: i32 = 3;
         println!("The value of x is {} and value of y is {}", x, y);
     }
-    println!("The value of x is {} and value of y is {}", x, y); // This won't work
+    println!("The value of x is {} and value of y is {}", x, y); // This won't work.
 }
 ```
 
@@ -207,7 +207,7 @@ Instead we get this error:
 $ cargo build
    Compiling hello v0.1.0 (file:///home/you/projects/hello_world)
 main.rs:7:62: 7:63 error: unresolved name `y`. Did you mean `x`? [E0425]
-main.rs:7     println!("The value of x is {} and value of y is {}", x, y); // This won't work
+main.rs:7     println!("The value of x is {} and value of y is {}", x, y); // This won't work.
                                                                        ^
 note: in expansion of format_args!
 <std macros>:2:25: 2:56 note: expansion site
@@ -229,13 +229,13 @@ scope will override the previous binding.
 ```rust
 let x: i32 = 8;
 {
-    println!("{}", x); // Prints "8"
+    println!("{}", x); // Prints "8".
     let x = 12;
-    println!("{}", x); // Prints "12"
+    println!("{}", x); // Prints "12".
 }
-println!("{}", x); // Prints "8"
+println!("{}", x); // Prints "8".
 let x =  42;
-println!("{}", x); // Prints "42"
+println!("{}", x); // Prints "42".
 ```
 
 Shadowing and mutable bindings may appear as two sides of the same coin, but
@@ -249,8 +249,8 @@ by any means.
 ```rust
 let mut x: i32 = 1;
 x = 7;
-let x = x; // x is now immutable and is bound to 7
+let x = x; // `x` is now immutable and is bound to `7`.
 
 let y = 4;
-let y = "I can also be bound to text!"; // y is now of a different type
+let y = "I can also be bound to text!"; // `y` is now of a different type.
 ```
diff --git a/src/doc/book/vectors.md b/src/doc/book/vectors.md
index cb6781cdf28..b948a54f44a 100644
--- a/src/doc/book/vectors.md
+++ b/src/doc/book/vectors.md
@@ -17,7 +17,7 @@ situation, this is just convention.)
 There’s an alternate form of `vec!` for repeating an initial value:
 
 ```rust
-let v = vec![0; 10]; // ten zeroes
+let v = vec![0; 10]; // A vector of ten zeroes.
 ```
 
 Vectors store their contents as contiguous arrays of `T` on the heap. This means
@@ -46,10 +46,10 @@ let v = vec![1, 2, 3, 4, 5];
 let i: usize = 0;
 let j: i32 = 0;
 
-// works
+// Works:
 v[i];
 
-// doesn’t
+// Doesn’t:
 v[j];
 ```