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

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,15 +126,15 @@ 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]
 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);
 }
 ```

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

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

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

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