Merging upstream version 1.66.0+dfsg1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 169 insertions, 238 deletions

diff --git a/src/doc/book/nostarch/chapter17.md b/src/doc/book/nostarch/chapter17.md
index f13b1484a..946d20a11 100644
--- a/src/doc/book/nostarch/chapter17.md
+++ b/src/doc/book/nostarch/chapter17.md
@@ -6,29 +6,24 @@ directory, so all fixes need to be made in `/src/`.
 
 [TOC]
 
-# Object-Oriented Programming Features of Rust
+# Object-Oriented Programming Features
 
 Object-oriented programming (OOP) is a way of modeling programs. Objects as a
 programmatic concept were introduced in the programming language Simula in the
 1960s. Those objects influenced Alan Kay’s programming architecture in which
 objects pass messages to each other. To describe this architecture, he coined
 the term *object-oriented programming* in 1967. Many competing definitions
-describe what OOP is, and by some of these definitions Rust is object-oriented,
+describe what OOP is, and by some of these definitions Rust is object oriented
 but by others it is not. In this chapter, we’ll explore certain characteristics
-that are commonly considered object-oriented and how those characteristics
+that are commonly considered object oriented and how those characteristics
 translate to idiomatic Rust. We’ll then show you how to implement an
 object-oriented design pattern in Rust and discuss the trade-offs of doing so
 versus implementing a solution using some of Rust’s strengths instead.
 
-<!-- Nit: we should probably use "object-oriented" throughout, rather using both
-"object-oriented" and "object oriented"
-/JT -->
-<!-- Done! /Carol -->
-
 ## Characteristics of Object-Oriented Languages
 
 There is no consensus in the programming community about what features a
-language must have to be considered object-oriented. Rust is influenced by many
+language must have to be considered object oriented. Rust is influenced by many
 programming paradigms, including OOP; for example, we explored the features
 that came from functional programming in Chapter 13. Arguably, OOP languages
 share certain common characteristics, namely objects, encapsulation, and
@@ -38,20 +33,20 @@ Rust supports it.
 ### Objects Contain Data and Behavior
 
 The book *Design Patterns: Elements of Reusable Object-Oriented Software* by
-Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides (Addison-Wesley
-Professional, 1994), colloquially referred to as *The Gang of Four* book, is a
-catalog of object-oriented design patterns. It defines OOP this way:
+Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides (Addison-Wesley,
+1994), colloquially referred to as *The Gang of Four* book, is a catalog of
+object-oriented design patterns. It defines OOP in this way:
 
-> Object-oriented programs are made up of objects. An *object* packages both
-> data and the procedures that operate on that data. The procedures are
-> typically called *methods* or *operations*.
+Object-oriented programs are made up of objects. An *object* packages both data
+and the procedures that operate on that data. The procedures are typically
+called *methods* or *operations*.
 
-Using this definition, Rust is object-oriented: structs and enums have data,
+Using this definition, Rust is object oriented: structs and enums have data,
 and `impl` blocks provide methods on structs and enums. Even though structs and
 enums with methods aren’t *called* objects, they provide the same
 functionality, according to the Gang of Four’s definition of objects.
 
-### Encapsulation that Hides Implementation Details
+### Encapsulation That Hides Implementation Details
 
 Another aspect commonly associated with OOP is the idea of *encapsulation*,
 which means that the implementation details of an object aren’t accessible to
@@ -66,10 +61,10 @@ keyword to decide which modules, types, functions, and methods in our code
 should be public, and by default everything else is private. For example, we
 can define a struct `AveragedCollection` that has a field containing a vector
 of `i32` values. The struct can also have a field that contains the average of
-the values in the vector, meaning the average doesn’t have to be computed
-on demand whenever anyone needs it. In other words, `AveragedCollection` will
+the values in the vector, meaning the average doesn’t have to be computed on
+demand whenever anyone needs it. In other words, `AveragedCollection` will
 cache the calculated average for us. Listing 17-1 has the definition of the
-`AveragedCollection` struct:
+`AveragedCollection` struct.
 
 Filename: src/lib.rs
 
@@ -87,7 +82,7 @@ The struct is marked `pub` so that other code can use it, but the fields within
 the struct remain private. This is important in this case because we want to
 ensure that whenever a value is added or removed from the list, the average is
 also updated. We do this by implementing `add`, `remove`, and `average` methods
-on the struct, as shown in Listing 17-2:
+on the struct, as shown in Listing 17-2.
 
 Filename: src/lib.rs
 
@@ -120,18 +115,12 @@ impl AveragedCollection {
 }
 ```
 
-<!-- The above example will crash with a division by zero if you call it at
-any time when it's empty. Not sure if we want to fix, but thought I'd point
-it out.
-/JT -->
-<!-- It actually won't because f64 / 0 is NaN, not a panic /Carol -->
-
 Listing 17-2: Implementations of the public methods `add`, `remove`, and
 `average` on `AveragedCollection`
 
 The public methods `add`, `remove`, and `average` are the only ways to access
-or modify data in an instance of `AveragedCollection`. When an item is added
-to `list` using the `add` method or removed using the `remove` method, the
+or modify data in an instance of `AveragedCollection`. When an item is added to
+`list` using the `add` method or removed using the `remove` method, the
 implementations of each call the private `update_average` method that handles
 updating the `average` field as well.
 
@@ -145,15 +134,15 @@ Because we’ve encapsulated the implementation details of the struct
 `AveragedCollection`, we can easily change aspects, such as the data structure,
 in the future. For instance, we could use a `HashSet<i32>` instead of a
 `Vec<i32>` for the `list` field. As long as the signatures of the `add`,
-`remove`, and `average` public methods stay the same, code using
+`remove`, and `average` public methods stayed the same, code using
 `AveragedCollection` wouldn’t need to change. If we made `list` public instead,
 this wouldn’t necessarily be the case: `HashSet<i32>` and `Vec<i32>` have
 different methods for adding and removing items, so the external code would
 likely have to change if it were modifying `list` directly.
 
-If encapsulation is a required aspect for a language to be considered
-object-oriented, then Rust meets that requirement. The option to use `pub` or
-not for different parts of code enables encapsulation of implementation details.
+If encapsulation is a required aspect for a language to be considered object
+oriented, then Rust meets that requirement. The option to use `pub` or not for
+different parts of code enables encapsulation of implementation details.
 
 ### Inheritance as a Type System and as Code Sharing
 
@@ -161,8 +150,8 @@ not for different parts of code enables encapsulation of implementation details.
 another object’s definition, thus gaining the parent object’s data and behavior
 without you having to define them again.
 
-If a language must have inheritance to be an object-oriented language, then
-Rust is not one. There is no way to define a struct that inherits the parent
+If a language must have inheritance to be object oriented, then Rust is not
+such a language. There is no way to define a struct that inherits the parent
 struct’s fields and method implementations without using a macro.
 
 However, if you’re used to having inheritance in your programming toolbox, you
@@ -182,22 +171,6 @@ also override the default implementation of the `summarize` method when we
 implement the `Summary` trait, which is similar to a child class overriding the
 implementation of a method inherited from a parent class.
 
-<!-- I'm a bit uncomfortable with the above. I think it's more honest to say
-that Rust doesn't support inheritance unless you use a macro. Saying to use
-the trait system to an OO programmer is going to leave them pretty confused, as
-traits lack of the basics of inheritance: you can't use and modify state, you
-have to use a surrogate type to hold the trait implementation, you can't
-instantiate, and so on.
-
-The example that came to mind: trying to teach OO programmers who want to
-build a UI library with traditional OO techniques using the trait system.
-It's unfortunately not going to work very well, if at all.
-
-A trait's main focus is polymorphism and not inheritance. It's probably
-better for folks coming from OO backgrounds if we just come out and say it, tbh.
-/JT -->
-<!-- I agree, and I've made some edits to the paragraphs above /Carol -->
-
 The other reason to use inheritance relates to the type system: to enable a
 child type to be used in the same places as the parent type. This is also
 called *polymorphism*, which means that you can substitute multiple objects for
@@ -206,12 +179,12 @@ each other at runtime if they share certain characteristics.
 > ### Polymorphism
 >
 > To many people, polymorphism is synonymous with inheritance. But it’s
-> actually a more general concept that refers to code that can work with data
-> of multiple types. For inheritance, those types are generally subclasses.
+actually a more general concept that refers to code that can work with data of
+multiple types. For inheritance, those types are generally subclasses.
 >
 > Rust instead uses generics to abstract over different possible types and
-> trait bounds to impose constraints on what those types must provide. This is
-> sometimes called *bounded parametric polymorphism*.
+trait bounds to impose constraints on what those types must provide. This is
+sometimes called *bounded parametric polymorphism*.
 
 Inheritance has recently fallen out of favor as a programming design solution
 in many programming languages because it’s often at risk of sharing more code
@@ -223,15 +196,6 @@ apply to the subclass. In addition, some languages will only allow single
 inheritance (meaning a subclass can only inherit from one class), further
 restricting the flexibility of a program’s design.
 
-<!-- Nit - "inherit from one class" and "single-inheritance" read a bit
-differently to me. Saying you inherit from only one class almost makes it sound
-like that the class you inherit from can't have a parent. Probably minor, just
-made me read that sentence a couple times.
-/JT -->
-<!-- I've included the term "single inheritance" above (it appears that usually
-it's not hyphenated) but kept what was there as an explanation in case the
-reader isn't familiar. /Carol -->
-
 For these reasons, Rust takes the different approach of using trait objects
 instead of inheritance. Let’s look at how trait objects enable polymorphism in
 Rust.
@@ -239,7 +203,7 @@ Rust.
 ## Using Trait Objects That Allow for Values of Different Types
 
 In Chapter 8, we mentioned that one limitation of vectors is that they can
-store elements of only one type. We created a workaround in Listing 8-10 where
+store elements of only one type. We created a workaround in Listing 8-9 where
 we defined a `SpreadsheetCell` enum that had variants to hold integers, floats,
 and text. This meant we could store different types of data in each cell and
 still have a vector that represented a row of cells. This is a perfectly good
@@ -257,7 +221,7 @@ some types for people to use, such as `Button` or `TextField`. In addition,
 instance, one programmer might add an `Image` and another might add a
 `SelectBox`.
 
-We won’t implement a fully fledged GUI library for this example but will show
+We won’t implement a full-fledged GUI library for this example but will show
 how the pieces would fit together. At the time of writing the library, we can’t
 know and define all the types other programmers might want to create. But we do
 know that `gui` needs to keep track of many values of different types, and it
@@ -283,12 +247,12 @@ implementing our specified trait and a table used to look up trait methods on
 that type at runtime. We create a trait object by specifying some sort of
 pointer, such as a `&` reference or a `Box<T>` smart pointer, then the `dyn`
 keyword, and then specifying the relevant trait. (We’ll talk about the reason
-trait objects must use a pointer in Chapter 19 in the section “Dynamically
-Sized Types and the `Sized` Trait.”) We can use trait objects in place of a
-generic or concrete type. Wherever we use a trait object, Rust’s type system
-will ensure at compile time that any value used in that context will implement
-the trait object’s trait. Consequently, we don’t need to know all the possible
-types at compile time.
+trait objects must use a pointer in “Dynamically Sized Types and the Sized
+Trait” on page XX.) We can use trait objects in place of a generic or concrete
+type. Wherever we use a trait object, Rust’s type system will ensure at compile
+time that any value used in that context will implement the trait object’s
+trait. Consequently, we don’t need to know all the possible types at compile
+time.
 
 We’ve mentioned that, in Rust, we refrain from calling structs and enums
 “objects” to distinguish them from other languages’ objects. In a struct or
@@ -302,7 +266,7 @@ languages: their specific purpose is to allow abstraction across common
 behavior.
 
 Listing 17-3 shows how to define a trait named `Draw` with one method named
-`draw`:
+`draw`.
 
 Filename: src/lib.rs
 
@@ -317,8 +281,8 @@ Listing 17-3: Definition of the `Draw` trait
 This syntax should look familiar from our discussions on how to define traits
 in Chapter 10. Next comes some new syntax: Listing 17-4 defines a struct named
 `Screen` that holds a vector named `components`. This vector is of type
-`Box<dyn Draw>`, which is a trait object; it’s a stand-in for any type inside
-a `Box` that implements the `Draw` trait.
+`Box<dyn Draw>`, which is a trait object; it’s a stand-in for any type inside a
+`Box` that implements the `Draw` trait.
 
 Filename: src/lib.rs
 
@@ -332,7 +296,7 @@ Listing 17-4: Definition of the `Screen` struct with a `components` field
 holding a vector of trait objects that implement the `Draw` trait
 
 On the `Screen` struct, we’ll define a method named `run` that will call the
-`draw` method on each of its `components`, as shown in Listing 17-5:
+`draw` method on each of its `components`, as shown in Listing 17-5.
 
 Filename: src/lib.rs
 
@@ -353,8 +317,8 @@ This works differently from defining a struct that uses a generic type
 parameter with trait bounds. A generic type parameter can only be substituted
 with one concrete type at a time, whereas trait objects allow for multiple
 concrete types to fill in for the trait object at runtime. For example, we
-could have defined the `Screen` struct using a generic type and a trait bound
-as in Listing 17-6:
+could have defined the `Screen` struct using a generic type and a trait bound,
+as in Listing 17-6.
 
 Filename: src/lib.rs
 
@@ -394,7 +358,7 @@ Now we’ll add some types that implement the `Draw` trait. We’ll provide the
 `Button` type. Again, actually implementing a GUI library is beyond the scope
 of this book, so the `draw` method won’t have any useful implementation in its
 body. To imagine what the implementation might look like, a `Button` struct
-might have fields for `width`, `height`, and `label`, as shown in Listing 17-7:
+might have fields for `width`, `height`, and `label`, as shown in Listing 17-7.
 
 Filename: src/lib.rs
 
@@ -425,8 +389,8 @@ happens when a user clicks the button. These kinds of methods won’t apply to
 types like `TextField`.
 
 If someone using our library decides to implement a `SelectBox` struct that has
-`width`, `height`, and `options` fields, they implement the `Draw` trait on the
-`SelectBox` type as well, as shown in Listing 17-8:
+`width`, `height`, and `options` fields, they would implement the `Draw` trait
+on the `SelectBox` type as well, as shown in Listing 17-8.
 
 Filename: src/main.rs
 
@@ -453,7 +417,7 @@ Our library’s user can now write their `main` function to create a `Screen`
 instance. To the `Screen` instance, they can add a `SelectBox` and a `Button`
 by putting each in a `Box<T>` to become a trait object. They can then call the
 `run` method on the `Screen` instance, which will call `draw` on each of the
-components. Listing 17-9 shows this implementation:
+components. Listing 17-9 shows this implementation.
 
 Filename: src/main.rs
 
@@ -484,12 +448,6 @@ fn main() {
 }
 ```
 
-<!-- I'd forgotten the UI components were in this chapter. To close on the
-thought from earlier: we don't use any inheritance in our example, only
-polymorphism. This probably is a vote for my earlier suggestion.
-/JT -->
-<!-- I indeed took the earlier suggestion. /Carol -->
-
 Listing 17-9: Using trait objects to store values of different types that
 implement the same trait
 
@@ -500,9 +458,9 @@ means it implements the `draw` method.
 
 This concept—of being concerned only with the messages a value responds to
 rather than the value’s concrete type—is similar to the concept of *duck
-typing* in dynamically typed languages: if it walks like a duck and quacks
-like a duck, then it must be a duck! In the implementation of `run` on `Screen`
-in Listing 17-5, `run` doesn’t need to know what the concrete type of each
+typing* in dynamically typed languages: if it walks like a duck and quacks like
+a duck, then it must be a duck! In the implementation of `run` on `Screen` in
+Listing 17-5, `run` doesn’t need to know what the concrete type of each
 component is. It doesn’t check whether a component is an instance of a `Button`
 or a `SelectBox`, it just calls the `draw` method on the component. By
 specifying `Box<dyn Draw>` as the type of the values in the `components`
@@ -516,7 +474,7 @@ if a value doesn’t implement a method but we call it anyway. Rust won’t comp
 our code if the values don’t implement the traits that the trait objects need.
 
 For example, Listing 17-10 shows what happens if we try to create a `Screen`
-with a `String` as a component:
+with a `String` as a component.
 
 Filename: src/main.rs
 
@@ -532,8 +490,8 @@ fn main() {
 }
 ```
 
-Listing 17-10: Attempting to use a type that doesn’t
-implement the trait object’s trait
+Listing 17-10: Attempting to use a type that doesn’t implement the trait
+object’s trait
 
 We’ll get this error because `String` doesn’t implement the `Draw` trait:
 
@@ -542,27 +500,28 @@ error[E0277]: the trait bound `String: Draw` is not satisfied
  --> src/main.rs:5:26
   |
 5 |         components: vec![Box::new(String::from("Hi"))],
-  |                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `Draw` is not implemented for `String`
+  |                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `Draw` is
+not implemented for `String`
   |
   = note: required for the cast to the object type `dyn Draw`
 ```
 
-This error lets us know that either we’re passing something to `Screen` we
-didn’t mean to pass and so should pass a different type or we should implement
+This error lets us know that either we’re passing something to `Screen` that we
+didn’t mean to pass and so should pass a different type, or we should implement
 `Draw` on `String` so that `Screen` is able to call `draw` on it.
 
 ### Trait Objects Perform Dynamic Dispatch
 
-Recall in the “Performance of Code Using Generics” section in Chapter 10 our
-discussion on the monomorphization process performed by the compiler when we
-use trait bounds on generics: the compiler generates nongeneric implementations
-of functions and methods for each concrete type that we use in place of a
-generic type parameter. The code that results from monomorphization is doing
-*static dispatch*, which is when the compiler knows what method you’re calling
-at compile time. This is opposed to *dynamic dispatch*, which is when the
-compiler can’t tell at compile time which method you’re calling. In dynamic
-dispatch cases, the compiler emits code that at runtime will figure out which
-method to call.
+Recall in “Performance of Code Using Generics” on page XX our discussion on the
+monomorphization process performed by the compiler when we use trait bounds on
+generics: the compiler generates nongeneric implementations of functions and
+methods for each concrete type that we use in place of a generic type
+parameter. The code that results from monomorphization is doing *static
+dispatch*, which is when the compiler knows what method you’re calling at
+compile time. This is opposed to *dynamic dispatch*, which is when the compiler
+can’t tell at compile time which method you’re calling. In dynamic dispatch
+cases, the compiler emits code that at runtime will figure out which method to
+call.
 
 When we use trait objects, Rust must use dynamic dispatch. The compiler doesn’t
 know all the types that might be used with the code that’s using trait objects,
@@ -581,26 +540,13 @@ pattern is that we define a set of states a value can have internally. The
 states are represented by a set of *state objects*, and the value’s behavior
 changes based on its state. We’re going to work through an example of a blog
 post struct that has a field to hold its state, which will be a state object
-from the set "draft", "review", or "published".
-<!-- can you give a quick example here, something we could visualize? are we
-saying "we define a set of states a value can have as state objects...."? /LC
--->
-<!-- What do you think about this, hinting at the coming example quickly? It
-felt weird to introduce something different only to switch gears in a few
-paragraphs, so is moving the example's introduction here ok? /Carol -->
-<!-- JT, what do you think? /LC -->
-<!-- Seems okay. My one thought coming to the end of the paragraph was "is
-this better than using an enum?" Not sure if we want to sidebar a bit on
-why we chose traits over enums, but some readers might be curious.
-/JT -->
-<!-- I've added a box later titled "Why Not An Enum?" to address this -- I
-think that makes a nice exercise for the reader :) /Carol -->
-
-The state objects share functionality: in Rust, of course, we use
-structs and traits rather than objects and inheritance. Each state object is
-responsible for its own behavior and for governing when it should change into
-another state. The value that holds a state object knows nothing about the
-different behavior of the states or when to transition between states.
+from the set “draft,” “review,” or “published.”
+
+The state objects share functionality: in Rust, of course, we use structs and
+traits rather than objects and inheritance. Each state object is responsible
+for its own behavior and for governing when it should change into another
+state. The value that holds a state object knows nothing about the different
+behavior of the states or when to transition between states.
 
 The advantage of using the state pattern is that, when the business
 requirements of the program change, we won’t need to change the code of the
@@ -608,18 +554,18 @@ value holding the state or the code that uses the value. We’ll only need to
 update the code inside one of the state objects to change its rules or perhaps
 add more state objects.
 
-First, we’re going to implement the state pattern in a more traditional
+First we’re going to implement the state pattern in a more traditional
 object-oriented way, then we’ll use an approach that’s a bit more natural in
-Rust. Let’s dig in to incrementally implementing a blog post workflow using the
+Rust. Let’s dig in to incrementally implement a blog post workflow using the
 state pattern.
 
 The final functionality will look like this:
 
 1. A blog post starts as an empty draft.
-2. When the draft is done, a review of the post is requested.
-3. When the post is approved, it gets published.
-4. Only published blog posts return content to print, so unapproved posts can’t
-   accidentally be published.
+1. When the draft is done, a review of the post is requested.
+1. When the post is approved, it gets published.
+1. Only published blog posts return content to print, so unapproved posts can’t
+accidentally be published.
 
 Any other changes attempted on a post should have no effect. For example, if we
 try to approve a draft blog post before we’ve requested a review, the post
@@ -635,16 +581,16 @@ Filename: src/main.rs
 use blog::Post;
 
 fn main() {
-    [1] let mut post = Post::new();
+  1 let mut post = Post::new();
 
-    [2] post.add_text("I ate a salad for lunch today");
-    [3] assert_eq!("", post.content());
+  2 post.add_text("I ate a salad for lunch today");
+  3 assert_eq!("", post.content());
 
-    [4] post.request_review();
-    [5] assert_eq!("", post.content());
+  4 post.request_review();
+  5 assert_eq!("", post.content());
 
-    [6] post.approve();
-    [7] assert_eq!("I ate a salad for lunch today", post.content());
+  6 post.approve();
+  7 assert_eq!("I ate a salad for lunch today", post.content());
 }
 ```
 
@@ -667,13 +613,13 @@ post will be returned when `content` is called [7].
 Notice that the only type we’re interacting with from the crate is the `Post`
 type. This type will use the state pattern and will hold a value that will be
 one of three state objects representing the various states a post can be
-in—draft, waiting for review, or published. Changing from one state to another
-will be managed internally within the `Post` type. The states change in
-response to the methods called by our library’s users on the `Post` instance,
-but they don’t have to manage the state changes directly. Also, users can’t
-make a mistake with the states, like publishing a post before it’s reviewed.
+in—draft, review, or published. Changing from one state to another will be
+managed internally within the `Post` type. The states change in response to the
+methods called by our library’s users on the `Post` instance, but they don’t
+have to manage the state changes directly. Also, users can’t make a mistake
+with the states, such as publishing a post before it’s reviewed.
 
-### Defining `Post` and Creating a New Instance in the Draft State
+### Defining Post and Creating a New Instance in the Draft State
 
 Let’s get started on the implementation of the library! We know we need a
 public `Post` struct that holds some content, so we’ll start with the
@@ -681,22 +627,6 @@ definition of the struct and an associated public `new` function to create an
 instance of `Post`, as shown in Listing 17-12. We’ll also make a private
 `State` trait that will define the behavior that all state objects for a `Post`
 must have.
-<!-- JT, I had a few questions here about what the state objects and state
-traits are doing. I'd appreciate your view on whether this all reads well with
-nothing missing! /LC -->
-<!-- Seems okay. If you're going to try to use a traditional OO approach in
-Rust, it'll have a bit of this style. I'm glad we include something that's a
-bit more Rust-y at the end of the chapter.
-
-What I might suggest is that we give the reader a bit of a roadmap here to say
-that we're going to explore two solutions to this problem. The first, a more
-traditional approach encoded into Rust, and the second, an approach that's more
-natural to Rust.
-/JT -->
-<!-- Great idea! I've added a bit in the introduction of this section above --
-"First, we’re going to implement the state pattern in a more traditional
-object-oriented way, then we’ll use an approach that’s a bit more natural in
-Rust." /Carol -->
 
 Then `Post` will hold a trait object of `Box<dyn State>` inside an `Option<T>`
 in a private field named `state` to hold the state object. You’ll see why the
@@ -713,8 +643,8 @@ pub struct Post {
 impl Post {
     pub fn new() -> Post {
         Post {
-            [1] state: Some(Box::new(Draft {})),
-            [2] content: String::new(),
+          1 state: Some(Box::new(Draft {})),
+          2 content: String::new(),
         }
     }
 }
@@ -737,9 +667,9 @@ want a post to start in.
 
 When we create a new `Post`, we set its `state` field to a `Some` value that
 holds a `Box` [1]. This `Box` points to a new instance of the `Draft` struct.
-This ensures whenever we create a new instance of `Post`, it will start out as
-a draft. Because the `state` field of `Post` is private, there is no way to
-create a `Post` in any other state! In the `Post::new` function, we set the
+This ensures that whenever we create a new instance of `Post`, it will start
+out as a draft. Because the `state` field of `Post` is private, there is no way
+to create a `Post` in any other state! In the `Post::new` function, we set the
 `content` field to a new, empty `String` [2].
 
 ### Storing the Text of the Post Content
@@ -750,13 +680,13 @@ blog post. We implement this as a method, rather than exposing the `content`
 field as `pub`, so that later we can implement a method that will control how
 the `content` field’s data is read. The `add_text` method is pretty
 straightforward, so let’s add the implementation in Listing 17-13 to the `impl
-Post` block:
+Post` block.
 
 Filename: src/lib.rs
 
 ```
 impl Post {
-    // --snip--
+    --snip--
     pub fn add_text(&mut self, text: &str) {
         self.content.push_str(text);
     }
@@ -766,7 +696,7 @@ impl Post {
 Listing 17-13: Implementing the `add_text` method to add text to a post’s
 `content`
 
-The `add_text` method takes a mutable reference to `self`, because we’re
+The `add_text` method takes a mutable reference to `self` because we’re
 changing the `Post` instance that we’re calling `add_text` on. We then call
 `push_str` on the `String` in `content` and pass the `text` argument to add to
 the saved `content`. This behavior doesn’t depend on the state the post is in,
@@ -783,13 +713,13 @@ implement the `content` method with the simplest thing that will fulfill this
 requirement: always returning an empty string slice. We’ll change this later
 once we implement the ability to change a post’s state so it can be published.
 So far, posts can only be in the draft state, so the post content should always
-be empty. Listing 17-14 shows this placeholder implementation:
+be empty. Listing 17-14 shows this placeholder implementation.
 
 Filename: src/lib.rs
 
 ```
 impl Post {
-    // --snip--
+    --snip--
     pub fn content(&self) -> &str {
         ""
     }
@@ -802,32 +732,32 @@ Listing 17-14: Adding a placeholder implementation for the `content` method on
 With this added `content` method, everything in Listing 17-11 up to the line at
 [3] works as intended.
 
-### Requesting a Review of the Post Changes Its State
+### Requesting a Review Changes the Post’s State
 
 Next, we need to add functionality to request a review of a post, which should
-change its state from `Draft` to `PendingReview`. Listing 17-15 shows this code:
+change its state from `Draft` to `PendingReview`. Listing 17-15 shows this code.
 
 Filename: src/lib.rs
 
 ```
 impl Post {
-    // --snip--
-    [1] pub fn request_review(&mut self) {
-        [2] if let Some(s) = self.state.take() {
-            [3] self.state = Some(s.request_review())
+    --snip--
+  1 pub fn request_review(&mut self) {
+      2 if let Some(s) = self.state.take() {
+          3 self.state = Some(s.request_review())
         }
     }
 }
 
 trait State {
-    [4] fn request_review(self: Box<Self>) -> Box<dyn State>;
+  4 fn request_review(self: Box<Self>) -> Box<dyn State>;
 }
 
 struct Draft {}
 
 impl State for Draft {
     fn request_review(self: Box<Self>) -> Box<dyn State> {
-        [5] Box::new(PendingReview {})
+      5 Box::new(PendingReview {})
     }
 }
 
@@ -835,7 +765,7 @@ struct PendingReview {}
 
 impl State for PendingReview {
     fn request_review(self: Box<Self>) -> Box<dyn State> {
-        [6] self
+      6 self
     }
 }
 ```
@@ -859,7 +789,7 @@ ownership of `Box<Self>`, invalidating the old state so the state value of the
 To consume the old state, the `request_review` method needs to take ownership
 of the state value. This is where the `Option` in the `state` field of `Post`
 comes in: we call the `take` method to take the `Some` value out of the `state`
-field and leave a `None` in its place, because Rust doesn’t let us have
+field and leave a `None` in its place because Rust doesn’t let us have
 unpopulated fields in structs [2]. This lets us move the `state` value out of
 `Post` rather than borrowing it. Then we’ll set the post’s `state` value to the
 result of this operation.
@@ -872,7 +802,7 @@ we’ve transformed it into a new state.
 The `request_review` method on `Draft` returns a new, boxed instance of a new
 `PendingReview` struct [5], which represents the state when a post is waiting
 for a review. The `PendingReview` struct also implements the `request_review`
-method but doesn’t do any transformations. Rather, it returns itself [6],
+method but doesn’t do any transformations. Rather, it returns itself [6]
 because when we request a review on a post already in the `PendingReview`
 state, it should stay in the `PendingReview` state.
 
@@ -885,17 +815,17 @@ slice. We can now have a `Post` in the `PendingReview` state as well as in the
 `Draft` state, but we want the same behavior in the `PendingReview` state.
 Listing 17-11 now works up to the line at [5]!
 
-### Adding `approve` to Change the Behavior of `content`
+### Adding approve to Change the Behavior of content
 
 The `approve` method will be similar to the `request_review` method: it will
 set `state` to the value that the current state says it should have when that
-state is approved, as shown in Listing 17-16:
+state is approved, as shown in Listing 17-16.
 
 Filename: src/lib.rs
 
 ```
 impl Post {
-    // --snip--
+    --snip--
     pub fn approve(&mut self) {
         if let Some(s) = self.state.take() {
             self.state = Some(s.approve())
@@ -911,18 +841,18 @@ trait State {
 struct Draft {}
 
 impl State for Draft {
-    // --snip--
+    --snip--
     fn approve(self: Box<Self>) -> Box<dyn State> {
-        [1] self
+      1 self
     }
 }
 
 struct PendingReview {}
 
 impl State for PendingReview {
-    // --snip--
+    --snip--
     fn approve(self: Box<Self>) -> Box<dyn State> {
-        [2] Box::new(Published {})
+      2 Box::new(Published {})
     }
 }
 
@@ -949,33 +879,33 @@ Similar to the way `request_review` on `PendingReview` works, if we call the
 return `self` [1]. When we call `approve` on `PendingReview`, it returns a new,
 boxed instance of the `Published` struct [2]. The `Published` struct implements
 the `State` trait, and for both the `request_review` method and the `approve`
-method, it returns itself, because the post should stay in the `Published`
-state in those cases.
+method, it returns itself because the post should stay in the `Published` state
+in those cases.
 
 Now we need to update the `content` method on `Post`. We want the value
 returned from `content` to depend on the current state of the `Post`, so we’re
 going to have the `Post` delegate to a `content` method defined on its `state`,
-as shown in Listing 17-17:
+as shown in Listing 17-17.
 
 Filename: src/lib.rs
 
 ```
 impl Post {
-    // --snip--
+    --snip--
     pub fn content(&self) -> &str {
         self.state.as_ref().unwrap().content(self)
     }
-    // --snip--
+    --snip--
 }
 ```
 
 Listing 17-17: Updating the `content` method on `Post` to delegate to a
 `content` method on `State`
 
-Because the goal is to keep all these rules inside the structs that implement
-`State`, we call a `content` method on the value in `state` and pass the post
-instance (that is, `self`) as an argument. Then we return the value that’s
-returned from using the `content` method on the `state` value.
+Because the goal is to keep all of these rules inside the structs that
+implement `State`, we call a `content` method on the value in `state` and pass
+the post instance (that is, `self`) as an argument. Then we return the value
+that’s returned from using the `content` method on the `state` value.
 
 We call the `as_ref` method on the `Option` because we want a reference to the
 value inside the `Option` rather than ownership of the value. Because `state`
@@ -983,37 +913,37 @@ is an `Option<Box<dyn State>>`, when we call `as_ref`, an `Option<&Box<dyn
 State>>` is returned. If we didn’t call `as_ref`, we would get an error because
 we can’t move `state` out of the borrowed `&self` of the function parameter.
 
-We then call the `unwrap` method, which we know will never panic, because we
+We then call the `unwrap` method, which we know will never panic because we
 know the methods on `Post` ensure that `state` will always contain a `Some`
 value when those methods are done. This is one of the cases we talked about in
-the “Cases In Which You Have More Information Than the Compiler” section of
-Chapter 9 when we know that a `None` value is never possible, even though the
-compiler isn’t able to understand that.
+“Cases in Which You Have More Information Than the Compiler” on page XX when we
+know that a `None` value is never possible, even though the compiler isn’t able
+to understand that.
 
 At this point, when we call `content` on the `&Box<dyn State>`, deref coercion
 will take effect on the `&` and the `Box` so the `content` method will
 ultimately be called on the type that implements the `State` trait. That means
 we need to add `content` to the `State` trait definition, and that is where
 we’ll put the logic for what content to return depending on which state we
-have, as shown in Listing 17-18:
+have, as shown in Listing 17-18.
 
 Filename: src/lib.rs
 
 ```
 trait State {
-    // --snip--
+    --snip--
     fn content<'a>(&self, post: &'a Post) -> &'a str {
-        [1] ""
+      1 ""
     }
 }
 
-// --snip--
+--snip--
 struct Published {}
 
 impl State for Published {
-    // --snip--
+    --snip--
     fn content<'a>(&self, post: &'a Post) -> &'a str {
-        [2] &post.content
+      2 &post.content
     }
 }
 ```
@@ -1021,9 +951,9 @@ impl State for Published {
 Listing 17-18: Adding the `content` method to the `State` trait
 
 We add a default implementation for the `content` method that returns an empty
-string slice [1]. That means we don’t need to implement `content` on the `Draft`
-and `PendingReview` structs. The `Published` struct will override the `content`
-method and return the value in `post.content` [2].
+string slice [1]. That means we don’t need to implement `content` on the
+`Draft` and `PendingReview` structs. The `Published` struct will override the
+`content` method and return the value in `post.content` [2].
 
 Note that we need lifetime annotations on this method, as we discussed in
 Chapter 10. We’re taking a reference to a `post` as an argument and returning a
@@ -1034,14 +964,14 @@ And we’re done—all of Listing 17-11 now works! We’ve implemented the state
 pattern with the rules of the blog post workflow. The logic related to the
 rules lives in the state objects rather than being scattered throughout `Post`.
 
-> #### Why Not An Enum?
+> ### Why Not An Enum?
 >
 > You may have been wondering why we didn’t use an `enum` with the different
-> possible post states as variants. That’s certainly a possible solution, try
-> it and compare the end results to see which you prefer! One disadvantage of
-> using an enum is every place that checks the value of the enum will need a
-> `match` expression or similar to handle every possible variant. This could
-> get more repetitive than this trait object solution.
+possible post states as variants. That’s certainly a possible solution; try it
+and compare the end results to see which you prefer! One disadvantage of using
+an enum is that every place that checks the value of the enum will need a
+`match` expression or similar to handle every possible variant. This could get
+more repetitive than this trait object solution.
 
 ### Trade-offs of the State Pattern
 
@@ -1069,11 +999,11 @@ functionality. To see the simplicity of maintaining code that uses the state
 pattern, try a few of these suggestions:
 
 * Add a `reject` method that changes the post’s state from `PendingReview` back
-  to `Draft`.
+to `Draft`.
 * Require two calls to `approve` before the state can be changed to `Published`.
 * Allow users to add text content only when a post is in the `Draft` state.
-  Hint: have the state object responsible for what might change about the
-  content but not responsible for modifying the `Post`.
+Hint: have the state object responsible for what might change about the content
+but not responsible for modifying the `Post`.
 
 One downside of the state pattern is that, because the states implement the
 transitions between states, some of the states are coupled to each other. If we
@@ -1085,22 +1015,22 @@ another design pattern.
 
 Another downside is that we’ve duplicated some logic. To eliminate some of the
 duplication, we might try to make default implementations for the
-`request_review` and `approve` methods on the `State` trait that return `self`;
-however, this would violate object safety, because the trait doesn’t know what
-the concrete `self` will be exactly. We want to be able to use `State` as a
-trait object, so we need its methods to be object safe.
+`request_review` and `approve` methods on the `State` trait that return `self`.
+However, this wouldn’t work: when using `State` as a trait object, the trait
+doesn’t know what the concrete `self` will be exactly, so the return type isn’t
+known at compile time.
 
 Other duplication includes the similar implementations of the `request_review`
 and `approve` methods on `Post`. Both methods delegate to the implementation of
 the same method on the value in the `state` field of `Option` and set the new
 value of the `state` field to the result. If we had a lot of methods on `Post`
 that followed this pattern, we might consider defining a macro to eliminate the
-repetition (see the “Macros” section in Chapter 19).
+repetition (see “Macros” on page XX).
 
 By implementing the state pattern exactly as it’s defined for object-oriented
 languages, we’re not taking as full advantage of Rust’s strengths as we could.
 Let’s look at some changes we can make to the `blog` crate that can make
-invalid states and transitions into compile time errors.
+invalid states and transitions into compile-time errors.
 
 #### Encoding States and Behavior as Types
 
@@ -1129,9 +1059,9 @@ and the ability to add text to the post’s content. But instead of having a
 draft posts don’t have the `content` method at all. That way, if we try to get
 a draft post’s content, we’ll get a compiler error telling us the method
 doesn’t exist. As a result, it will be impossible for us to accidentally
-display draft post content in production, because that code won’t even compile.
+display draft post content in production because that code won’t even compile.
 Listing 17-19 shows the definition of a `Post` struct and a `DraftPost` struct,
-as well as methods on each:
+as well as methods on each.
 
 Filename: src/lib.rs
 
@@ -1145,19 +1075,19 @@ pub struct DraftPost {
 }
 
 impl Post {
-    [1] pub fn new() -> DraftPost {
+  1 pub fn new() -> DraftPost {
         DraftPost {
             content: String::new(),
         }
     }
 
-    [2] pub fn content(&self) -> &str {
+  2 pub fn content(&self) -> &str {
         &self.content
     }
 }
 
 impl DraftPost {
-    [3] pub fn add_text(&mut self, text: &str) {
+  3 pub fn add_text(&mut self, text: &str) {
         self.content.push_str(text);
     }
 }
@@ -1189,15 +1119,15 @@ So how do we get a published post? We want to enforce the rule that a draft
 post has to be reviewed and approved before it can be published. A post in the
 pending review state should still not display any content. Let’s implement
 these constraints by adding another struct, `PendingReviewPost`, defining the
-`request_review` method on `DraftPost` to return a `PendingReviewPost`, and
+`request_review` method on `DraftPost` to return a `PendingReviewPost` and
 defining an `approve` method on `PendingReviewPost` to return a `Post`, as
-shown in Listing 17-20:
+shown in Listing 17-20.
 
 Filename: src/lib.rs
 
 ```
 impl DraftPost {
-    // --snip--
+    --snip--
     pub fn request_review(self) -> PendingReviewPost {
         PendingReviewPost {
             content: self.content,
@@ -1240,7 +1170,7 @@ called on, so we need to add more `let post =` shadowing assignments to save
 the returned instances. We also can’t have the assertions about the draft and
 pending review posts’ contents be empty strings, nor do we need them: we can’t
 compile code that tries to use the content of posts in those states any longer.
-The updated code in `main` is shown in Listing 17-21:
+The updated code in `main` is shown in Listing 17-21.
 
 Filename: src/main.rs
 
@@ -1287,16 +1217,17 @@ object-oriented languages don’t have.
 
 ## Summary
 
-No matter whether or not you think Rust is an object-oriented language after
+Regardless of whether you think Rust is an object-oriented language after
 reading this chapter, you now know that you can use trait objects to get some
 object-oriented features in Rust. Dynamic dispatch can give your code some
 flexibility in exchange for a bit of runtime performance. You can use this
 flexibility to implement object-oriented patterns that can help your code’s
 maintainability. Rust also has other features, like ownership, that
 object-oriented languages don’t have. An object-oriented pattern won’t always
-be the best way to take advantage of Rust’s strengths, but is an available
+be the best way to take advantage of Rust’s strengths, but it is an available
 option.
 
 Next, we’ll look at patterns, which are another of Rust’s features that enable
 lots of flexibility. We’ve looked at them briefly throughout the book but
 haven’t seen their full capability yet. Let’s go!
+