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

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

r? @GuillaumeGomez

Author: bors

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.
 }
 ```
 

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)
 });
 ```

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,
 }
 

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
     }

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.
 ```
 
 

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;
 ```

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

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;
 

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 {

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.
 }
 ```