diff --git a/second-edition/nostarch/chapter14.md b/second-edition/nostarch/chapter14.md index 48e1c962c..a0c986b97 100644 --- a/second-edition/nostarch/chapter14.md +++ b/second-edition/nostarch/chapter14.md @@ -147,11 +147,11 @@ For convenience, running `cargo doc --open` will build the HTML for your current crate’s documentation (as well as the documentation for all of your crate’s dependencies) and open the result in a web browser. Navigate to the `add_one` function and you’ll see how the text in the documentation comments -gets rendered, shown here in Figure 14-2: +gets rendered, shown here in Figure 14-1: -Rendered HTML documentation for the `add_one` function of `my_crate` +Rendered HTML documentation for the `add_one` function of `my_crate` -Figure 14-2: HTML documentation for the `add_one` function +Figure 14-1: HTML documentation for the `add_one` function #### Commonly Used Sections @@ -209,7 +209,7 @@ module as a whole. For example, if we wanted to add documentation that described the purpose of the `my_crate` crate that contains the `add_one` function, we can add documentation comments that start with `//!` to the beginning of *src/lib.rs* -as shown in Listing 14-3: +as shown in Listing 14-2: Filename: src/lib.rs @@ -223,7 +223,7 @@ Filename: src/lib.rs // --snip-- ``` -Listing 14-3: Documentation for the `my_crate` crate as a whole +Listing 14-2: Documentation for the `my_crate` crate as a whole Notice there isn’t any code after the last line that begins with `//!`. Because we started the comments with `//!` instead of `///`, we’re documenting the item @@ -233,11 +233,11 @@ is the crate root. These comments describe the entire crate. If we run `cargo doc --open`, we’ll see these comments displayed on the front page of the documentation for `my_crate` above the list of public items in the -crate, as shown in Figure 14-4: +crate, as shown in Figure 14-2: -Rendered HTML documentation with a comment for the crate as a whole +Rendered HTML documentation with a comment for the crate as a whole -Figure 14-4: Rendered documentation for `my_crate` including the comment +Figure 14-2: Rendered documentation for `my_crate` including the comment describing the crate as a whole Documentation comments within items are useful for describing crates and @@ -272,7 +272,7 @@ the other location instead. For example, say we made a library named `art` for modeling artistic concepts. Within this library is a `kinds` module containing two enums named `PrimaryColor` and `SecondaryColor` and a `utils` module containing a function -named `mix` as shown in Listing 14-5: +named `mix` as shown in Listing 14-3: Filename: src/lib.rs @@ -308,15 +308,15 @@ pub mod utils { } ``` -Listing 14-5: An `art` library with items organized into `kinds` and `utils` +Listing 14-3: An `art` library with items organized into `kinds` and `utils` modules The front page of the documentation for this crate generated by `cargo doc` -would look like Figure 14-6: +would look like Figure 14-3: -Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules +Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules -Figure 14-6: Front page of the documentation for `art` that lists the `kinds` +Figure 14-3: Front page of the documentation for `art` that lists the `kinds` and `utils` modules Note that the `PrimaryColor` and `SecondaryColor` types aren’t listed on the @@ -325,7 +325,7 @@ in order to see them. Another crate depending on this library would need `use` statements that import the items from `art` including specifying the module structure that’s currently -defined. Listing 14-7 shows an example of a crate that uses the `PrimaryColor` +defined. Listing 14-4 shows an example of a crate that uses the `PrimaryColor` and `mix` items from the `art` crate: Filename: src/main.rs @@ -343,10 +343,10 @@ fn main() { } ``` -Listing 14-7: A crate using the `art` crate’s items with its internal structure +Listing 14-4: A crate using the `art` crate’s items with its internal structure exported -The author of the code in Listing 14-7 that uses the `art` crate had to figure +The author of the code in Listing 14-4 that uses the `art` crate had to figure out that `PrimaryColor` is in the `kinds` module and `mix` is in the `utils` module. The module structure of the `art` crate is more relevant to developers working on the `art` crate than developers using the `art` crate. The internal @@ -357,8 +357,8 @@ confusion in having to figure out where to look and inconvenience in having to specify the module names in the `use` statements. To remove the internal organization from the public API, we can take the `art` -crate code from Listing 14-5 and add `pub use` statements to re-export the -items at the top level, as shown in Listing 14-8: +crate code from Listing 14-3 and add `pub use` statements to re-export the +items at the top level, as shown in Listing 14-5: Filename: src/lib.rs @@ -380,20 +380,19 @@ pub mod utils { } ``` -Listing 14-8: Adding `pub use` statements to re-export items +Listing 14-5: Adding `pub use` statements to re-export items The API documentation generated with `cargo doc` for this crate will now list -and link re-exports on the front page as shown in Figure 14-9, which makes +and link re-exports on the front page as shown in Figure 14-4, which makes these types easier to find. -Rendered documentation for the `art` crate with the re-exports on the front page +Rendered documentation for the `art` crate with the re-exports on the front page -Figure 14-9: Front page of the documentation for `art` that lists the -re-exports +Figure 14-4: Front page of the documentation for `art` that lists the re-exports Users of the `art` crate can still see and choose to use the internal structure -as in Listing 14-7, or they can use the more convenient structure from Listing -14-8, as shown in Listing 14-10: +as in Listing 14-3, or they can use the more convenient structure from Listing +14-5, as shown in Listing 14-6: Filename: src/main.rs @@ -408,7 +407,7 @@ fn main() { } ``` -Listing 14-10: A program using the re-exported items from the `art` crate +Listing 14-6: A program using the re-exported items from the `art` crate In cases where there are many nested modules, re-exporting the types at the top level with `pub use` can make a big difference in the experience of people who @@ -687,7 +686,7 @@ pub fn add_one(x: i32) -> i32 { Open up *src/main.rs* for `adder` and add an `extern crate` line at the top of the file to bring the new `add-one` library crate into scope. Then change the -`main` function to call the `add_one` function, as in Listing 14-11: +`main` function to call the `add_one` function, as in Listing 14-7: Filename: src/main.rs @@ -700,7 +699,7 @@ fn main() { } ``` -Listing 14-11: Using the `add-one` library crate from the `adder` crate +Listing 14-7: Using the `add-one` library crate from the `adder` crate Let’s build the `adder` crate by running `cargo build` in the *adder* directory! diff --git a/second-edition/src/ch14-02-publishing-to-crates-io.md b/second-edition/src/ch14-02-publishing-to-crates-io.md index 6d8490edb..7d6d0ccc1 100644 --- a/second-edition/src/ch14-02-publishing-to-crates-io.md +++ b/second-edition/src/ch14-02-publishing-to-crates-io.md @@ -56,11 +56,11 @@ For convenience, running `cargo doc --open` will build the HTML for your current crate’s documentation (as well as the documentation for all of your crate’s dependencies) and open the result in a web browser. Navigate to the `add_one` function and you’ll see how the text in the documentation comments -gets rendered, shown here in Figure 14-2: +gets rendered, shown here in Figure 14-1: -Rendered HTML documentation for the `add_one` function of `my_crate` +Rendered HTML documentation for the `add_one` function of `my_crate` -Figure 14-2: HTML documentation for the `add_one` +Figure 14-1: HTML documentation for the `add_one` function #### Commonly Used Sections @@ -119,7 +119,7 @@ module as a whole. For example, if we wanted to add documentation that described the purpose of the `my_crate` crate that contains the `add_one` function, we can add documentation comments that start with `//!` to the beginning of *src/lib.rs* -as shown in Listing 14-3: +as shown in Listing 14-2: Filename: src/lib.rs @@ -133,7 +133,7 @@ as shown in Listing 14-3: // --snip-- ``` -Listing 14-3: Documentation for the `my_crate` crate as a +Listing 14-2: Documentation for the `my_crate` crate as a whole Notice there isn’t any code after the last line that begins with `//!`. Because @@ -144,11 +144,11 @@ is the crate root. These comments describe the entire crate. If we run `cargo doc --open`, we’ll see these comments displayed on the front page of the documentation for `my_crate` above the list of public items in the -crate, as shown in Figure 14-4: +crate, as shown in Figure 14-2: -Rendered HTML documentation with a comment for the crate as a whole +Rendered HTML documentation with a comment for the crate as a whole -Figure 14-4: Rendered documentation for `my_crate` +Figure 14-2: Rendered documentation for `my_crate` including the comment describing the crate as a whole Documentation comments within items are useful for describing crates and @@ -183,7 +183,7 @@ the other location instead. For example, say we made a library named `art` for modeling artistic concepts. Within this library is a `kinds` module containing two enums named `PrimaryColor` and `SecondaryColor` and a `utils` module containing a function -named `mix` as shown in Listing 14-5: +named `mix` as shown in Listing 14-3: Filename: src/lib.rs @@ -219,15 +219,15 @@ pub mod utils { } ``` -Listing 14-5: An `art` library with items organized into +Listing 14-3: An `art` library with items organized into `kinds` and `utils` modules The front page of the documentation for this crate generated by `cargo doc` -would look like Figure 14-6: +would look like Figure 14-3: -Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules +Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules -Figure 14-6: Front page of the documentation for `art` +Figure 14-3: Front page of the documentation for `art` that lists the `kinds` and `utils` modules Note that the `PrimaryColor` and `SecondaryColor` types aren’t listed on the @@ -236,7 +236,7 @@ in order to see them. Another crate depending on this library would need `use` statements that import the items from `art` including specifying the module structure that’s currently -defined. Listing 14-7 shows an example of a crate that uses the `PrimaryColor` +defined. Listing 14-4 shows an example of a crate that uses the `PrimaryColor` and `mix` items from the `art` crate: Filename: src/main.rs @@ -254,10 +254,10 @@ fn main() { } ``` -Listing 14-7: A crate using the `art` crate’s items with +Listing 14-4: A crate using the `art` crate’s items with its internal structure exported -The author of the code in Listing 14-7 that uses the `art` crate had to figure +The author of the code in Listing 14-4 that uses the `art` crate had to figure out that `PrimaryColor` is in the `kinds` module and `mix` is in the `utils` module. The module structure of the `art` crate is more relevant to developers working on the `art` crate than developers using the `art` crate. The internal @@ -268,8 +268,8 @@ confusion in having to figure out where to look and inconvenience in having to specify the module names in the `use` statements. To remove the internal organization from the public API, we can take the `art` -crate code from Listing 14-5 and add `pub use` statements to re-export the -items at the top level, as shown in Listing 14-8: +crate code from Listing 14-3 and add `pub use` statements to re-export the +items at the top level, as shown in Listing 14-5: Filename: src/lib.rs @@ -291,21 +291,21 @@ pub mod utils { } ``` -Listing 14-8: Adding `pub use` statements to re-export +Listing 14-5: Adding `pub use` statements to re-export items The API documentation generated with `cargo doc` for this crate will now list -and link re-exports on the front page as shown in Figure 14-9, which makes +and link re-exports on the front page as shown in Figure 14-4, which makes these types easier to find. -Rendered documentation for the `art` crate with the re-exports on the front page +Rendered documentation for the `art` crate with the re-exports on the front page -Figure 14-9: Front page of the documentation for `art` +Figure 14-4: Front page of the documentation for `art` that lists the re-exports Users of the `art` crate can still see and choose to use the internal structure -as in Listing 14-7, or they can use the more convenient structure from Listing -14-8, as shown in Listing 14-10: +as in Listing 14-3, or they can use the more convenient structure from Listing +14-5, as shown in Listing 14-6: Filename: src/main.rs @@ -320,7 +320,7 @@ fn main() { } ``` -Listing 14-10: A program using the re-exported items from +Listing 14-6: A program using the re-exported items from the `art` crate In cases where there are many nested modules, re-exporting the types at the top diff --git a/second-edition/src/ch14-03-cargo-workspaces.md b/second-edition/src/ch14-03-cargo-workspaces.md index d1f63f5a6..747ca299a 100644 --- a/second-edition/src/ch14-03-cargo-workspaces.md +++ b/second-edition/src/ch14-03-cargo-workspaces.md @@ -92,7 +92,7 @@ pub fn add_one(x: i32) -> i32 { Open up *src/main.rs* for `adder` and add an `extern crate` line at the top of the file to bring the new `add-one` library crate into scope. Then change the -`main` function to call the `add_one` function, as in Listing 14-11: +`main` function to call the `add_one` function, as in Listing 14-7: Filename: src/main.rs @@ -105,7 +105,7 @@ fn main() { } ``` -Listing 14-11: Using the `add-one` library crate from the +Listing 14-7: Using the `add-one` library crate from the `adder` crate Let’s build the `adder` crate by running `cargo build` in the *adder* directory! diff --git a/second-edition/src/img/trpl14-01.png b/second-edition/src/img/trpl14-01.png new file mode 100644 index 000000000..5fc59898c Binary files /dev/null and b/second-edition/src/img/trpl14-01.png differ diff --git a/second-edition/src/img/trpl14-05.png b/second-edition/src/img/trpl14-02.png similarity index 100% rename from second-edition/src/img/trpl14-05.png rename to second-edition/src/img/trpl14-02.png diff --git a/second-edition/src/img/trpl14-03.png b/second-edition/src/img/trpl14-03.png index 5fc59898c..ef8414507 100644 Binary files a/second-edition/src/img/trpl14-03.png and b/second-edition/src/img/trpl14-03.png differ diff --git a/second-edition/src/img/trpl14-10.png b/second-edition/src/img/trpl14-04.png similarity index 100% rename from second-edition/src/img/trpl14-10.png rename to second-edition/src/img/trpl14-04.png diff --git a/second-edition/src/img/trpl14-07.png b/second-edition/src/img/trpl14-07.png deleted file mode 100644 index ef8414507..000000000 Binary files a/second-edition/src/img/trpl14-07.png and /dev/null differ