Backport fixes from NoStarch [status: through Ch. 19]

listings/ch03-common-programming-concepts/no-listing-24-comments-end-of-line/src/main.rs

@@ -1,3 +1,3 @@
 fn main() {
-    let lucky_number = 7; // I’m feeling lucky today
+    let lucky_number = 7; // I'm feeling lucky today
 }

listings/ch03-common-programming-concepts/no-listing-25-comments-above-line/src/main.rs

@@ -1,4 +1,4 @@
 fn main() {
-    // I’m feeling lucky today
+    // I'm feeling lucky today
     let lucky_number = 7;
 }

listings/ch04-understanding-ownership/listing-04-04/src/main.rs

@@ -1,29 +1,30 @@
 fn main() {
-    let s1 = gives_ownership();         // gives_ownership moves its return
-                                        // value into s1
+    let s1 = gives_ownership();        // gives_ownership moves its return
+                                       // value into s1
 
-    let s2 = String::from("hello");     // s2 comes into scope
+    let s2 = String::from("hello");    // s2 comes into scope
 
-    let s3 = takes_and_gives_back(s2);  // s2 is moved into
-                                        // takes_and_gives_back, which also
-                                        // moves its return value into s3
+    let s3 = takes_and_gives_back(s2); // s2 is moved into
+                                       // takes_and_gives_back, which also
+                                       // moves its return value into s3
 } // Here, s3 goes out of scope and is dropped. s2 was moved, so nothing
   // happens. s1 goes out of scope and is dropped.
 
-fn gives_ownership() -> String {             // gives_ownership will move its
-                                             // return value into the function
-                                             // that calls it
+fn gives_ownership() -> String {       // gives_ownership will move its
+                                       // return value into the function
+                                       // that calls it
 
     let some_string = String::from("yours"); // some_string comes into scope
 
-    some_string                              // some_string is returned and
-                                             // moves out to the calling
-                                             // function
+    some_string                        // some_string is returned and
+                                       // moves out to the calling
+                                       // function
 }
 
-// This function takes a String and returns one
-fn takes_and_gives_back(a_string: String) -> String { // a_string comes into
-                                                      // scope
+// This function takes a String and returns a String.
+fn takes_and_gives_back(a_string: String) -> String {
+    // a_string comes into
+    // scope
 
     a_string  // a_string is returned and moves out to the calling function
 }

listings/ch04-understanding-ownership/listing-04-09/src/main.rs

@@ -16,16 +16,17 @@ fn first_word(s: &str) -> &str {
 fn main() {
     let my_string = String::from("hello world");
 
-    // `first_word` works on slices of `String`s, whether partial or whole
+    // `first_word` works on slices of `String`s, whether partial or whole.
     let word = first_word(&my_string[0..6]);
     let word = first_word(&my_string[..]);
     // `first_word` also works on references to `String`s, which are equivalent
-    // to whole slices of `String`s
+    // to whole slices of `String`s.
     let word = first_word(&my_string);
 
     let my_string_literal = "hello world";
 
-    // `first_word` works on slices of string literals, whether partial or whole
+    // `first_word` works on slices of string literals, whether partial or
+    // whole.
     let word = first_word(&my_string_literal[0..6]);
     let word = first_word(&my_string_literal[..]);
 

listings/ch04-understanding-ownership/no-listing-13-reference-scope-ends/src/main.rs

@@ -5,7 +5,7 @@ fn main() {
     let r1 = &s; // no problem
     let r2 = &s; // no problem
     println!("{r1} and {r2}");
-    // variables r1 and r2 will not be used after this point
+    // Variables r1 and r2 will not be used after this point.
 
     let r3 = &mut s; // no problem
     println!("{r3}");

listings/ch04-understanding-ownership/no-listing-15-dangling-reference-annotated/src/main.rs

@@ -8,6 +8,6 @@ fn dangle() -> &String { // dangle returns a reference to a String
     let s = String::from("hello"); // s is a new String
 
     &s // we return a reference to the String, s
-} // Here, s goes out of scope, and is dropped. Its memory goes away.
+} // Here, s goes out of scope, and is dropped, so its memory goes away.
   // Danger!
-// ANCHOR_END: here
+  // ANCHOR_END: here

listings/ch07-managing-growing-projects/listing-07-05/src/lib.rs

@@ -1,9 +1,12 @@
+// ANCHOR: here
 mod front_of_house {
     pub mod hosting {
         fn add_to_waitlist() {}
     }
 }
 
+// -- snip --
+// ANCHOR_END: here
 pub fn eat_at_restaurant() {
     // Absolute path
     crate::front_of_house::hosting::add_to_waitlist();

listings/ch07-managing-growing-projects/listing-07-07/src/lib.rs

@@ -1,9 +1,12 @@
+// ANCHOR: here
 mod front_of_house {
     pub mod hosting {
         pub fn add_to_waitlist() {}
     }
 }
 
+// -- snip --
+// ANCHOR_END: here
 pub fn eat_at_restaurant() {
     // Absolute path
     crate::front_of_house::hosting::add_to_waitlist();

listings/ch07-managing-growing-projects/listing-07-09/src/lib.rs

@@ -15,13 +15,13 @@ mod back_of_house {
 }
 
 pub fn eat_at_restaurant() {
-    // Order a breakfast in the summer with Rye toast
+    // Order a breakfast in the summer with Rye toast.
     let mut meal = back_of_house::Breakfast::summer("Rye");
-    // Change our mind about what bread we'd like
+    // Change our mind about what bread we'd like.
     meal.toast = String::from("Wheat");
     println!("I'd like {} toast please", meal.toast);
 
     // The next line won't compile if we uncomment it; we're not allowed
-    // to see or modify the seasonal fruit that comes with the meal
+    // to see or modify the seasonal fruit that comes with the meal.
     // meal.seasonal_fruit = String::from("blueberries");
 }

listings/ch08-common-collections/listing-08-12/src/main.rs

@@ -4,7 +4,7 @@ fn main() {
 
     let s = data.to_string();
 
-    // the method also works on a literal directly:
+    // The method also works on a literal directly:
     let s = "initial contents".to_string();
     // ANCHOR_END: here
 }

listings/ch15-smart-pointers/listing-15-26/src/main.rs

@@ -38,7 +38,7 @@ fn main() {
     println!("a rc count after changing a = {}", Rc::strong_count(&a));
 
     // Uncomment the next line to see that we have a cycle;
-    // it will overflow the stack
+    // it will overflow the stack.
     // println!("a next item = {:?}", a.tail());
 }
 // ANCHOR_END: here

src/ch01-03-hello-cargo.md

@@ -66,8 +66,6 @@ name = "hello_cargo"
 version = "0.1.0"
 edition = "2021"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
 ```
 

src/ch02-00-guessing-game-tutorial.md

@@ -857,7 +857,7 @@ If `parse` is _not_ able to turn the string into a number, it will return an
 `Err` value that contains more information about the error. The `Err` value
 does not match the `Ok(num)` pattern in the first `match` arm, but it does
 match the `Err(_)` pattern in the second arm. The underscore, `_`, is a
-catchall value; in this example, we’re saying we want to match all `Err`
+catch-all value; in this example, we’re saying we want to match all `Err`
 values, no matter what information they have inside them. So the program will
 execute the second arm’s code, `continue`, which tells the program to go to the
 next iteration of the `loop` and ask for another guess. So, effectively, the

src/ch03-02-data-types.md

@@ -62,11 +62,11 @@ when it’s safe to assume the number is positive, it’s shown with no sign.
 Signed numbers are stored using [two’s complement][twos-complement]<!-- ignore
 --> representation.
 
-Each signed variant can store numbers from -(2<sup>n - 1</sup>) to 2<sup>n -
-1</sup> - 1 inclusive, where _n_ is the number of bits that variant uses. So an
-`i8` can store numbers from -(2<sup>7</sup>) to 2<sup>7</sup> - 1, which equals
--128 to 127. Unsigned variants can store numbers from 0 to 2<sup>n</sup> - 1,
-so a `u8` can store numbers from 0 to 2<sup>8</sup> - 1, which equals 0 to 255.
+Each signed variant can store numbers from −(2<sup>n − 1</sup>) to 2<sup>n −
+1</sup> − 1 inclusive, where _n_ is the number of bits that variant uses. So an
+`i8` can store numbers from −(2<sup>7</sup>) to 2<sup>7</sup> − 1, which equals
+−128 to 127. Unsigned variants can store numbers from 0 to 2<sup>n</sup> − 1,
+so a `u8` can store numbers from 0 to 2<sup>8</sup> − 1, which equals 0 to 255.
 
 Additionally, the `isize` and `usize` types depend on the architecture of the
 computer your program is running on, which is denoted in the table as “arch”:
@@ -120,7 +120,7 @@ some sort of collection.
 >
 > - Wrap in all modes with the `wrapping_*` methods, such as `wrapping_add`.
 > - Return the `None` value if there is overflow with the `checked_*` methods.
-> - Return the value and a boolean indicating whether there was overflow with
+> - Return the value and a Boolean indicating whether there was overflow with
 >   the `overflowing_*` methods.
 > - Saturate at the value’s minimum or maximum values with the `saturating_*`
 >   methods.

src/ch03-04-comments.md

@@ -16,9 +16,9 @@ comment continues until the end of the line. For comments that extend beyond a
 single line, you’ll need to include `//` on each line, like this:
 
 ```rust
-// So we’re doing something complicated here, long enough that we need
+// So we're doing something complicated here, long enough that we need
 // multiple lines of comments to do it! Whew! Hopefully, this comment will
-// explain what’s going on.
+// explain what's going on.
 ```
 
 Comments can also be placed at the end of lines containing code:

src/ch06-02-match.md

@@ -193,7 +193,7 @@ possibility in order for the code to be valid. Especially in the case of
 `None` case, it protects us from assuming that we have a value when we might
 have null, thus making the billion-dollar mistake discussed earlier impossible.
 
-### Catch-all Patterns and the `_` Placeholder
+### Catch-All Patterns and the `_` Placeholder
 
 Using enums, we can also take special actions for a few particular values, but
 for all other values take one default action. Imagine we’re implementing a game

src/ch07-00-managing-growing-projects-with-packages-crates-and-modules.md

@@ -12,7 +12,7 @@ optionally one library crate. As a package grows, you can extract parts into
 separate crates that become external dependencies. This chapter covers all
 these techniques. For very large projects comprising a set of interrelated
 packages that evolve together, Cargo provides _workspaces_, which we’ll cover
-in the [“Cargo Workspaces”][workspaces]<!-- ignore --> section in Chapter 14.
+in [“Cargo Workspaces”][workspaces]<!-- ignore --> in Chapter 14.
 
 We’ll also discuss encapsulating implementation details, which lets you reuse
 code at a higher level: once you’ve implemented an operation, other code can

src/ch07-01-packages-and-crates.md

@@ -4,14 +4,14 @@ The first parts of the module system we’ll cover are packages and crates.
 
 A _crate_ is the smallest amount of code that the Rust compiler considers at a
 time. Even if you run `rustc` rather than `cargo` and pass a single source code
-file (as we did all the way back in the “Writing and Running a Rust Program”
-section of Chapter 1), the compiler considers that file to be a crate. Crates
-can contain modules, and the modules may be defined in other files that get
-compiled with the crate, as we’ll see in the coming sections.
+file (as we did all the way back in “Writing and Running a Rust Program” in
+Chapter 1), the compiler considers that file to be a crate. Crates can contain
+modules, and the modules may be defined in other files that get compiled with
+the crate, as we’ll see in the coming sections.
 
 A crate can come in one of two forms: a binary crate or a library crate.
 _Binary crates_ are programs you can compile to an executable that you can run,
-such as a command-line program or a server. Each must have a function called
+such as a command line program or a server. Each must have a function called
 `main` that defines what happens when the executable runs. All the crates we’ve
 created so far have been binary crates.
 
@@ -23,17 +23,16 @@ Most of the time when Rustaceans say “crate”, they mean library crate, and t
 use “crate” interchangeably with the general programming concept of a “library”.
 
 The _crate root_ is a source file that the Rust compiler starts from and makes
-up the root module of your crate (we’ll explain modules in depth in the
-[“Defining Modules to Control Scope and Privacy”][modules]<!-- ignore -->
-section).
+up the root module of your crate (we’ll explain modules in depth in [“Defining
+Modules to Control Scope and Privacy”][modules]<!-- ignore -->).
 
 A _package_ is a bundle of one or more crates that provides a set of
 functionality. A package contains a _Cargo.toml_ file that describes how to
 build those crates. Cargo is actually a package that contains the binary crate
-for the command-line tool you’ve been using to build your code. The Cargo
+for the command line tool you’ve been using to build your code. The Cargo
 package also contains a library crate that the binary crate depends on. Other
 projects can depend on the Cargo library crate to use the same logic the Cargo
-command-line tool uses. A package can contain as many binary crates as you
+command line tool uses. A package can contain as many binary crates as you
 like, but at most only one library crate. A package must contain at least one
 crate, whether that’s a library or binary crate.
 

src/ch07-03-paths-for-referring-to-an-item-in-the-module-tree.md

@@ -108,7 +108,7 @@ access to the `add_to_waitlist` function in the child module, so we mark the
 <Listing number="7-5" file-name="src/lib.rs" caption="Declaring the `hosting` module as `pub` to use it from `eat_at_restaurant`">
 
 ```rust,ignore,does_not_compile
-{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-05/src/lib.rs}}
+{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-05/src/lib.rs:here}}
 ```
 
 </Listing>
@@ -143,7 +143,7 @@ keyword before its definition, as in Listing 7-7.
 <Listing number="7-7" file-name="src/lib.rs" caption="Adding the `pub` keyword to `mod hosting` and `fn add_to_waitlist` lets us call the function from `eat_at_restaurant`">
 
 ```rust,noplayground,test_harness
-{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-07/src/lib.rs}}
+{{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-07/src/lib.rs:here}}
 ```
 
 </Listing>
@@ -174,7 +174,7 @@ If you plan on sharing your library crate so other projects can use your code,
 your public API is your contract with users of your crate that determines how
 they can interact with your code. There are many considerations around managing
 changes to your public API to make it easier for people to depend on your
-crate. These considerations are out of the scope of this book; if you’re
+crate. These considerations are beyond the scope of this book; if you’re
 interested in this topic, see [The Rust API Guidelines][api-guidelines].
 
 > #### Best Practices for Packages with a Binary and a Library
@@ -195,7 +195,7 @@ interested in this topic, see [The Rust API Guidelines][api-guidelines].
 > client!
 >
 > In [Chapter 12][ch12]<!-- ignore -->, we’ll demonstrate this organizational
-> practice with a command-line program that will contain both a binary crate
+> practice with a command line program that will contain both a binary crate
 > and a library crate.
 
 ### Starting Relative Paths with `super`
@@ -268,7 +268,7 @@ have such a function, we couldn’t create an instance of `Breakfast` in
 In contrast, if we make an enum public, all of its variants are then public. We
 only need the `pub` before the `enum` keyword, as shown in Listing 7-10.
 
-<Listing number="7-10" file-name="src/lib.rs" caption="Designating an enum as public makes all its variants public">
+<Listing number="7-10" file-name="src/lib.rs" caption="Designating an enum as public makes all its variants public.">
 
 ```rust,noplayground
 {{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-10/src/lib.rs}}

src/ch07-04-bringing-paths-into-scope-with-the-use-keyword.md

@@ -31,7 +31,7 @@ Note that `use` only creates the shortcut for the particular scope in which the
 child module named `customer`, which is then a different scope than the `use`
 statement, so the function body won’t compile.
 
-<Listing number="7-12" file-name="src/lib.rs" caption="A `use` statement only applies in the scope it’s in">
+<Listing number="7-12" file-name="src/lib.rs" caption="A `use` statement only applies in the scope it’s in.">
 
 ```rust,noplayground,test_harness,does_not_compile,ignore
 {{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-12/src/lib.rs}}
@@ -159,13 +159,12 @@ Re-exporting is useful when the internal structure of your code is different
 from how programmers calling your code would think about the domain. For
 example, in this restaurant metaphor, the people running the restaurant think
 about “front of house” and “back of house.” But customers visiting a restaurant
-probably won’t think about the parts of the restaurant in those terms. With
-`pub use`, we can write our code with one structure but expose a different
-structure. Doing so makes our library well organized for programmers working on
-the library and programmers calling the library. We’ll look at another example
-of `pub use` and how it affects your crate’s documentation in the [“Exporting a
-Convenient Public API with `pub use`”][ch14-pub-use]<!-- ignore --> section of
-Chapter 14.
+probably won’t think about the parts of the restaurant in those terms. With `pub
+use`, we can write our code with one structure but expose a different structure.
+Doing so makes our library well organized for programmers working on the library
+and programmers calling the library. We’ll look at another example of `pub use`
+and how it affects your crate’s documentation in [“Exporting a Convenient Public
+API with `pub use`”][ch14-pub-use]<!-- ignore --> in Chapter 14.
 
 ### Using External Packages
 
@@ -192,10 +191,10 @@ Adding `rand` as a dependency in _Cargo.toml_ tells Cargo to download the
 make `rand` available to our project.
 
 Then, to bring `rand` definitions into the scope of our package, we added a
-`use` line starting with the name of the crate, `rand`, and listed the items
-we wanted to bring into scope. Recall that in the [“Generating a Random
-Number”][rand]<!-- ignore --> section in Chapter 2, we brought the `Rng` trait
-into scope and called the `rand::thread_rng` function:
+`use` line starting with the name of the crate, `rand`, and listed the items we
+wanted to bring into scope. Recall that in [“Generating a Random
+Number”][rand]<!-- ignore --> in Chapter 2, we brought the `Rng` trait into
+scope and called the `rand::thread_rng` function:
 
 ```rust,ignore
 {{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-03/src/main.rs:ch07-04}}
@@ -292,11 +291,12 @@ the current scope. Be careful when using the glob operator! Glob can make it
 harder to tell what names are in scope and where a name used in your program
 was defined.
 
-The glob operator is often used when testing to bring everything under test
-into the `tests` module; we’ll talk about that in the [“How to Write
-Tests”][writing-tests]<!-- ignore --> section in Chapter 11. The glob operator
-is also sometimes used as part of the prelude pattern: see [the standard library documentation](../std/prelude/index.html#other-preludes)<!-- ignore -->
-for more information on that pattern.
+The glob operator is often used when testing to bring everything under test into
+the `tests` module; we’ll talk about that in [“How to Write
+Tests”][writing-tests]<!-- ignore --> in Chapter 11. The glob operator is also
+sometimes used as part of the prelude pattern: see [the standard library
+documentation](../std/prelude/index.html#other-preludes)<!-- ignore --> for more
+information on that pattern.
 
 [ch14-pub-use]: ch14-02-publishing-to-crates-io.html#exporting-a-convenient-public-api-with-pub-use
 [rand]: ch02-00-guessing-game-tutorial.html#generating-a-random-number