Redo listing/figure numberings in chapter 14
Figures and Listings have their own sequence. And fix the filenames of the screenshots so they match.
@@ -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:
|
||||
|
||||
<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 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:
|
||||
|
||||
<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 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.
|
||||
|
||||
<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
|
||||
|
||||
Let’s build the `adder` crate by running `cargo build` in the *adder* directory!
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
<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 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:
|
||||
|
||||
<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 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:
|
||||
|
||||
<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` crate’s items with
|
||||
<span class="caption">Listing 14-4: A crate using the `art` crate’s 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
|
||||
|
||||
@@ -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>
|
||||
|
||||
Let’s build the `adder` crate by running `cargo build` in the *adder* directory!
|
||||
|
||||
BIN
second-edition/src/img/trpl14-01.png
Normal file
|
After Width: | Height: | Size: 64 KiB |
|
Before Width: | Height: | Size: 172 KiB After Width: | Height: | Size: 172 KiB |
|
Before Width: | Height: | Size: 64 KiB After Width: | Height: | Size: 42 KiB |
|
Before Width: | Height: | Size: 67 KiB After Width: | Height: | Size: 67 KiB |
|
Before Width: | Height: | Size: 42 KiB |