Redo listing/figure numberings in chapter 14

Figures and Listings have their own sequence.

And fix the filenames of the screenshots so they match.
This commit is contained in:
Carol (Nichols || Goulding)
2018-01-10 13:05:26 -05:00
parent 594725f20e
commit 9877ecd08f
8 changed files with 54 additions and 55 deletions

View File

@@ -147,11 +147,11 @@ For convenience, running `cargo doc --open` will build the HTML for your
current crates documentation (as well as the documentation for all of your
crates dependencies) and open the result in a web browser. Navigate to the
`add_one` function and youll see how the text in the documentation comments
gets rendered, shown here in Figure 14-2:
gets rendered, shown here in Figure 14-1:
<img alt="Rendered HTML documentation for the `add_one` function of `my_crate`" src="img/trpl14-03.png" class="center" />
<img alt="Rendered HTML documentation for the `add_one` function of `my_crate`" src="img/trpl14-01.png" class="center" />
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 isnt any code after the last line that begins with `//!`. Because
we started the comments with `//!` instead of `///`, were documenting the item
@@ -233,11 +233,11 @@ is the crate root. These comments describe the entire crate.
If we run `cargo doc --open`, well 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:
<img alt="Rendered HTML documentation with a comment for the crate as a whole" src="img/trpl14-05.png" class="center" />
<img alt="Rendered HTML documentation with a comment for the crate as a whole" src="img/trpl14-02.png" class="center" />
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:
<img alt="Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules" src="img/trpl14-07.png" class="center" />
<img alt="Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules" src="img/trpl14-03.png" class="center" />
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 arent 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 thats 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` crates items with its internal structure
Listing 14-4: A crate using the `art` crates 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.
<img alt="Rendered documentation for the `art` crate with the re-exports on the front page" src="img/trpl14-10.png" class="center" />
<img alt="Rendered documentation for the `art` crate with the re-exports on the front page" src="img/trpl14-04.png" class="center" />
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
Lets build the `adder` crate by running `cargo build` in the *adder* directory!

View File

@@ -56,11 +56,11 @@ For convenience, running `cargo doc --open` will build the HTML for your
current crates documentation (as well as the documentation for all of your
crates dependencies) and open the result in a web browser. Navigate to the
`add_one` function and youll see how the text in the documentation comments
gets rendered, shown here in Figure 14-2:
gets rendered, shown here in Figure 14-1:
<img alt="Rendered HTML documentation for the `add_one` function of `my_crate`" src="img/trpl14-03.png" class="center" />
<img alt="Rendered HTML documentation for the `add_one` function of `my_crate`" src="img/trpl14-01.png" class="center" />
<span class="caption">Figure 14-2: HTML documentation for the `add_one`
<span class="caption">Figure 14-1: HTML documentation for the `add_one`
function</span>
#### 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:
<span class="filename">Filename: src/lib.rs</span>
@@ -133,7 +133,7 @@ as shown in Listing 14-3:
// --snip--
```
<span class="caption">Listing 14-3: Documentation for the `my_crate` crate as a
<span class="caption">Listing 14-2: Documentation for the `my_crate` crate as a
whole</span>
Notice there isnt 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`, well 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:
<img alt="Rendered HTML documentation with a comment for the crate as a whole" src="img/trpl14-05.png" class="center" />
<img alt="Rendered HTML documentation with a comment for the crate as a whole" src="img/trpl14-02.png" class="center" />
<span class="caption">Figure 14-4: Rendered documentation for `my_crate`
<span class="caption">Figure 14-2: Rendered documentation for `my_crate`
including the comment describing the crate as a whole</span>
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:
<span class="filename">Filename: src/lib.rs</span>
@@ -219,15 +219,15 @@ pub mod utils {
}
```
<span class="caption">Listing 14-5: An `art` library with items organized into
<span class="caption">Listing 14-3: An `art` library with items organized into
`kinds` and `utils` modules</span>
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:
<img alt="Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules" src="img/trpl14-07.png" class="center" />
<img alt="Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules" src="img/trpl14-03.png" class="center" />
<span class="caption">Figure 14-6: Front page of the documentation for `art`
<span class="caption">Figure 14-3: Front page of the documentation for `art`
that lists the `kinds` and `utils` modules</span>
Note that the `PrimaryColor` and `SecondaryColor` types arent 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 thats 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:
<span class="filename">Filename: src/main.rs</span>
@@ -254,10 +254,10 @@ fn main() {
}
```
<span class="caption">Listing 14-7: A crate using the `art` crates items with
<span class="caption">Listing 14-4: A crate using the `art` crates items with
its internal structure exported</span>
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:
<span class="filename">Filename: src/lib.rs</span>
@@ -291,21 +291,21 @@ pub mod utils {
}
```
<span class="caption">Listing 14-8: Adding `pub use` statements to re-export
<span class="caption">Listing 14-5: Adding `pub use` statements to re-export
items</span>
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.
<img alt="Rendered documentation for the `art` crate with the re-exports on the front page" src="img/trpl14-10.png" class="center" />
<img alt="Rendered documentation for the `art` crate with the re-exports on the front page" src="img/trpl14-04.png" class="center" />
<span class="caption">Figure 14-9: Front page of the documentation for `art`
<span class="caption">Figure 14-4: Front page of the documentation for `art`
that lists the re-exports</span>
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:
<span class="filename">Filename: src/main.rs</span>
@@ -320,7 +320,7 @@ fn main() {
}
```
<span class="caption">Listing 14-10: A program using the re-exported items from
<span class="caption">Listing 14-6: A program using the re-exported items from
the `art` crate</span>
In cases where there are many nested modules, re-exporting the types at the top

View File

@@ -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:
<span class="filename">Filename: src/main.rs</span>
@@ -105,7 +105,7 @@ fn main() {
}
```
<span class="caption">Listing 14-11: Using the `add-one` library crate from the
<span class="caption">Listing 14-7: Using the `add-one` library crate from the
`adder` crate</span>
Lets build the `adder` crate by running `cargo build` in the *adder* directory!

Binary file not shown.

After

Width:  |  Height:  |  Size: 64 KiB

View File

Before

Width:  |  Height:  |  Size: 172 KiB

After

Width:  |  Height:  |  Size: 172 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 64 KiB

After

Width:  |  Height:  |  Size: 42 KiB

View File

Before

Width:  |  Height:  |  Size: 67 KiB

After

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 42 KiB