diff --git a/projects/art/Cargo.toml b/projects/art/Cargo.toml index 4742a18..f16924b 100644 --- a/projects/art/Cargo.toml +++ b/projects/art/Cargo.toml @@ -1,8 +1,6 @@ [package] name = "art" version = "0.1.0" -edition = "2021" - -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +edition = "2024" [dependencies] diff --git a/projects/art/src/kinds.rs b/projects/art/src/kinds.rs deleted file mode 100644 index d5a9a30..0000000 --- a/projects/art/src/kinds.rs +++ /dev/null @@ -1,15 +0,0 @@ -/// RYB 颜色模型下的主要颜色。 -#[derive(Debug)] -pub enum PrimaryColor { - Red, - Yellow, - Blue, -} - -/// RYB 颜色模型下的次要颜色。 -#[derive(Debug)] -pub enum SecondaryColor { - Orange, - Green, - Purple, -} diff --git a/projects/art/src/lib.rs b/projects/art/src/lib.rs index 594292e..bfbaa15 100644 --- a/projects/art/src/lib.rs +++ b/projects/art/src/lib.rs @@ -1,10 +1,36 @@ -//! # art +//! # 美术 //! -//! 建模诸多美术概念的一个库。 - -pub mod kinds; -pub mod utils; +//! 用于建模美术概念的库。 pub use self::kinds::PrimaryColor; pub use self::kinds::SecondaryColor; pub use self::utils::mix; + + +pub mod kinds { + /// 根据 RYB 颜色模型的原色。 + pub enum PrimaryColor { + Red, + Yellow, + Blue, + } + + /// 根据 RYB 颜色模型的间色。 + #[derive(Debug)] + pub enum SecondaryColor { + Orange, + Green, + Purple, + } +} + +pub mod utils { + use crate::kinds::*; + + /// 等量组合两种原色以创建 + /// 一种间色。 + pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor { + // --跳过代码-- + SecondaryColor::Purple + } +} diff --git a/projects/art/src/utils.rs b/projects/art/src/utils.rs deleted file mode 100644 index 8de81af..0000000 --- a/projects/art/src/utils.rs +++ /dev/null @@ -1,9 +0,0 @@ -use crate::kinds::*; - -/// 结合两种等量的主要颜色，创建出 -/// 某种次要颜色。 -pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor { - // --跳过代码-- - println! ("c1: {:?}, c2: {:?}", c1, c2); - SecondaryColor::Purple -} diff --git a/projects/art_user/Cargo.toml b/projects/art_user/Cargo.toml new file mode 100644 index 0000000..77d231b --- /dev/null +++ b/projects/art_user/Cargo.toml @@ -0,0 +1,7 @@ +[package] +name = "art_user" +version = "0.1.0" +edition = "2024" + +[dependencies] +art = { path = "../art" } diff --git a/projects/art_user/src/main.rs b/projects/art_user/src/main.rs new file mode 100644 index 0000000..748ce6d --- /dev/null +++ b/projects/art_user/src/main.rs @@ -0,0 +1,10 @@ +use art::mix; +use art::PrimaryColor; + +fn main() { + let red = PrimaryColor::Red; + let yellow = PrimaryColor::Yellow; + let result = mix(red, yellow); + + println! ("{result:#?}"); +} diff --git a/src/crates-io/publishing.md b/src/crates-io/publishing.md index 6459d65..8fe9895 100644 --- a/src/crates-io/publishing.md +++ b/src/crates-io/publishing.md @@ -122,44 +122,45 @@ test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; fini **清单 14-2**：`my_crate` 代码箱作为一个整体的文档 -请注意由于咱们是以 `//!` 而非 `///` 开始的这些注释，因此在以 `//!` 开始的最后一行后，并无任何代码的，咱们是在给包含此注释的程序项目，而非紧接着此注释的程序项目编写文档。在此示例中，那个程序项目就是 `src/lib.rs` 文件，为代码箱根。这些注释描述了整个代码箱。 +请注意，以 `//!` 开头的最后一行之后没有任何代码。由于我们以 `//!` 而不是 `///` 开始注释，因此我们是在给包含这种注释的程序项目，而非紧接着这种注释之后的程序项目编写文档。在这一情形下，该项目是 `src/lib.rs` 文件，是代码箱根。这些注释描述了整个代码箱。 -当咱们运行 `cargo doc --open` 时，这些注释将显示在 `cargo_features_demo` 代码箱文档的首页，he front page，位处代码箱公开项目的清单之上，如下图 14-02 中所示： +当我们运行 `cargo doc --open` 时，这些注释将显示在 `my_crate` 代码箱文档的首页，在代码箱的公开项目列表上方，如下图 14-2 中所示： + ![渲染出的 `cargo_features_demo` 代码箱文档](../images/14-02.png) -*图 14-02：渲染出的 `cargo_features_demo` 代码箱文档, 包括着将该代码箱作为整体描述的注释* +**图 14-02**：`my_crate` 渲染后的文档, 包括作为整体描述该代码箱的注释 -程序项目里的文档注释，用于对描述代码箱及模组尤其有用。使用他们来解释容器，the container，的整体目标，有助于咱们的用户们理解代码箱的组织结构。 +项目内的文档注释对于描述代码箱及模组尤其有用。请使用他们说明容器的总体用途，以帮助咱们的用户理解代码箱的组织结构。 -## 导出便利的公开 API +## 导出便捷的公开 API +在发布代码箱时，公开 API 的结构属于主要考量。相比咱们自己，使用代码箱的人对代码箱结构的没有那么熟悉，当咱们的代码箱有着庞大的模组层次结构时，他们可能在找到他们打算使用的部分时遇到困难。 -在咱们发布代码箱时，公开 API 的结构是主要的考量。相比与咱们，使用咱们代码箱的人们对代码箱结构的没有那么熟悉，并在咱们的代码箱有着大型模组层次结构时，难于找到他们打算使用的部分。 +在第 7 章中，咱们介绍了怎样使用 `pub` 关键字构造项目为公开，以及怎样以 `use` 关键字带入项目到作用域。然而，在开发代码箱时对咱们有意义的组织结构（模组树），对于咱们的用户可能并不方便。咱们可能打算组织咱们的结构为包含多个级别的层次结构，但后来打算使用某个咱们定义在层次结构深处的类型的人，可能在找出该类型是否存在时遇到麻烦。他们可能还会因为不得不输入 `my_crate::some_module::another_module::UsefulType;`，而不是输入 `use my_crate::UsefulType;` 而感到恼火。 -在第 7 章中，咱们曾讲到过怎样使用 `pub` 关键字把一些程序项目构造为公开，与怎样使用 `use` 关键字，把程序项目带入到作用域。但是，咱们在开发某个代码箱时，对咱们有意义的组织结构（模组树），对于咱们的用户则可能不那么便利。咱们会打算把代码箱结构组织为包含多个级别的层次，但随后某个想要使用定义在层次结构深处类型的人，就可能在找出那个类型是否存在上遇到麻烦。他们可能还会对必须敲入 `use cargo_features_demo::some_module::another_module::UsefulType;`，而非敲入 `use cargo_features_demo::UsefulType;` 而感到恼火。 +好消息是，当组织结构 *不* 便于其他人在另一库中使用时，咱们不必调整咱们的内部组织结构：相反，咱们可以通过使用 `pub use` 重新导出程序项目，以构造一种不同于咱们的私有组织结构的公开组织结构。所谓 *重新导出*，会取位于一处的某个公开程序项目，并构造其为在另一处公开，就像他被定义在另一处一样。 -可喜的是，若代码箱组织结构 *不* 便于其他人在另一库中使用，咱们不必重新调整代码箱的内部组织：相反，咱们可通过使用 `pub use`，重新导出程序项目，而构造出一种不同于咱们私有组织结构的公开组织结构。重新导出，re-export，会取一处的公开程序项目，而在另一处将其构造为公开，就跟这个项目是在那另一处被定义过一样。 - -比如说，咱们构造了用于建模美术概念的一个名为 `art` 的库。这个库里有两个模组：包含了两个名为 `PrimaryColor` 与 `SeccondaryColor` 枚举的 `kinds` 模组，与包含了名为 `mix` 函数的 `utils` 模组，如下清单 14-3 中所示： +例如，假设我们出于建模美术概念目的，构造了一个名为 `art` 的库。这个库内有两个模组：包含两个名为 `PrimaryColor` 与 `SeccondaryColor` 枚举的 `kinds` 模组，和包含名为 `mix` 函数的 `utils` 模组，如下清单 14-3 中所示： + 文件名：`src/lib.rs` ```rust -//! # art +//! # 美术 //! -//! 建模诸多美术概念的一个库。 +//! 用于建模美术概念的库。 pub mod kinds { - /// RYB 颜色模型下的主要颜色。 + /// 根据 RYB 颜色模型的原色。 pub enum PrimaryColor { Red, Yellow, Blue, } - /// RYB 颜色模型下的次要颜色。 + /// 根据 RYB 颜色模型的间色。 pub enum SecondaryColor { Orange, Green, @@ -170,8 +171,8 @@ pub mod kinds { pub mod utils { use crate::kinds::*; - /// 结合两种等量的主要颜色，创建出 - /// 某种次要颜色。 + /// 等量组合两种原色以创建 + /// 一种间色。 pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor { // --跳过代码-- SecondaryColor::Purple @@ -179,19 +180,20 @@ pub mod utils { } ``` -*清单 14-3：有着组织到 `kinds` 与 `utils` 两个模组中的一些程序项目的 `art` 库* +**清单 14-3**：`art` 库，有着组织在 `kinds` 与 `utils` 两个模组中的程序项目 -下图 14-03 展示了由 `cargo doc` 产生出的该代码箱文档首页，看起来的样子： +下图 14-03 展示了由 `cargo doc` 生成的这个代码箱的文档的首页的样子： + ![列出 `kinds` 与 `utils` 两个模组的 `art` 代码箱文档首页](../images/14-03.png) -*图 14-3：列出 `kinds` 与 `utils` 两个模组的 `art` 代码箱文档首页* +**图 14-3**：`art` 库的文档的首页，列出了 `kinds` 与 `utils` 两个模组 +请注意，`PrimaryColor` 与 `SecondaryColor` 两个类型并未在首页上列出，`mix` 函数也如此。我们必须点击 `kinds` 与 `utils` 才能看到他们。 -请注意 `PrimaryColor` 与 `SecondaryColor` 两个类型，及 `mix` 函数都未在首页上列出。要看到他们，咱们必须点击 `kinds` 与 `utils`。 - -依赖于这个库的另一代码箱，将需要把程序项目从 `art` 带入到作用域的 `use` 语句，与指明当前定义的模组结构。下面清单 14-4 给出了用到 `art` 代码箱中 `PrimaryColor` 与 `mix` 两个程序项目的代码箱示例： +依赖于这个库的另一代码箱将需要 `use` 语句，带入 `art` 中的项目到作用域，指定当前定义的模组结构。下面清单 14-4 展示了一个代码箱示例，使用 `art` 代码箱中的 `PrimaryColor` 与 `mix` 两个程序项目： + 文件名：`src/main.rs` ```rust @@ -205,23 +207,24 @@ fn main() { } ``` -*清单 14-4：用到 `art` 代码箱以内部组织结构导出程序项目的代码箱* +**清单 14-4**：使用 `art` 代码箱的项目的代码箱，`art` 代码箱的内部组织结构已导出 -> **注**：使用本地未发布代码箱的方法，是在 `Cargo.toml` 的 `[dependencies]` 小节中，列出要使用的本地未发布代码箱。参见 [How to use a local unpublished crate?](https://stackoverflow.com/a/33025972) +> **译注**：使用本地未发布代码箱的方法，是在 `Cargo.toml` 的 `[dependencies]` 小节中，列出要使用的本地未发布代码箱。参见 [How to use a local unpublished crate?](https://stackoverflow.com/a/33025972) +> +> 文件：`Cargo.toml` +> +> ```toml +> // --跳过代码-- +> +> [dependencies] +> art = { path = "../art" } +> ``` -文件：`Cargo.toml` +清单 14-4 中使用 `art` 代码箱的代码的作者，必须搞清楚 `PrimaryColor` 位于 `kinds` 模组中，而 `mix` 位于 `utils` 模组中。`art` 代码箱的模组结构（即模组树），相比使用他的人，对于编写 `art` 代码箱的开发者更为密切。对于试图了解怎样使用 `art` 代码箱的人来说，这一内部组织结构并未包含任何有用信息，反而会造成混淆，因为使用他的开发者必须弄清楚在哪里去查看，并且必须在 `use` 语句中指定模组名字。 -```toml -// --跳过代码-- - -[dependencies] -art = { path = "../art" } -``` - -清单 14-4 中用到 `art` 代码箱代码的作者，不得不搞清楚 `PrimaryColor` 是在 `kinds` 模组中，及 `mix` 函数是在 `utils` 模组中。`art` 代码箱的模组结构（即模组树），相比于用到该代码箱的开发者，与在 `art` 代码箱上编写代码的开发者要更为密切。对于试图搞清楚怎样使用 `art` 代码箱的人来说，其内部组织结构并未包含任何有用信息，而因为要用到他的开发者，不得不搞明白要在那里去查看，且必须在 `use` 语句中指明那些模组名字，这反而会造成混乱。 - -要从公开 API 中移除内部组织结构，咱们可把清单 14-3 中 `art` 代码箱的代码，修改为添加一些 `pub use` 语句，来在顶层处重导出程序项目，to re-export the items at the top level，如下清单 14-5 中所示： +为了移除公开 API 中的内部组织结构，我们可以修改 [清单 14-3](#listing_14-3) 中 `art` 代码箱的代码，为添加一些 `pub use` 语句，以在顶层重新导出程序项目，如下清单 14-5 中所示： + 文件名：`src/lib.rs` ```rust @@ -233,20 +236,27 @@ pub use self::kinds::PrimaryColor; pub use self::kinds::SecondaryColor; pub use self::utils::mix; -pub mod kinds; -pub mod utils; +pub mod kinds { + // -- 跳过代码 -- +} + +pub mod utils { + // -- 跳过代码 -- +} ``` -*清单 14-5：添加 `pub use` 语句来重导出程序项目* +**清单 14-5**：添加 `pub use` 语句以重新导出程序项目 -如下图 14-04 中所示，`cargo doc` 为此代码箱所产生出的 API 文档，现在将在首页上列出并链接到重导出项，从而令到 `PrimaryColor` 与 `SecondaryColor` 两个类型及 `mix` 函数更易于找到。 +如下图 14-04 中所示，`cargo doc` 对这个代码箱生成的 API 文档，现在将在首页上列出并链接到重导出项，从而让 `PrimaryColor` 与 `SecondaryColor` 两个类型以及 `mix` 函数更容易找到。 + ![列出了重导出项目的 `art` 代码箱文档首页](../images/14-04.png) -*图 14-4：列出重导出项的 `art` 代码箱文档首页* +**图 14-4**：`art` 代码箱文档的首页，列出了重新导出项目 -`art` 代码箱的用户，依然可以像清单 14-4 中所演示的那样，发现及使用清单 14-3 的内部结构，或者他们可使用清单 14-5 中更为便利的结构，如下清单 14-6 中所示： +`art` 代码箱的用户仍然可以如同 [清单 14-4](#listing_14-4) 中演示的那样，看到并使用 [清单 14-3](#listing_14-3) 中的内部结构，或者他们可使用清单 14-5 中的更方便的结构，如下清单 14-6 中所示： + 文件名：`src/main.rs` ```rust @@ -260,11 +270,11 @@ fn main() { } ``` -*清单 14-6：使用着 `art` 代码箱重导出项的程序* +**清单 14-6**：使用 `art` 代码箱中重新导出项目的程序 -其中有许多嵌套模组的情形下，以 `pub use` 在顶层重导出类型，可在用到该代码箱的人的体验方面，造成显著不同。`pub use` 的另一常见用途则是，为将依赖代码箱的定义构造为咱们自己代码箱公开 API 的一部分，而重导出当前代码箱中某个依赖的定义。 +在存在许多嵌套模组的情形下，以 `pub use` 在顶层重新导出类型，可以对使用代码箱的人的体验造成显著差异。`pub use` 的另一个常见用途是重新导出当前代码箱中的依赖项的定义，以使该代码箱的定义，成为咱们的代码箱的公开 API 的一部分。 -创建出有用的公开 API 结构，与其说是一门科学，不如说是一门艺术，而咱们可不断迭代，来找到对用户运作最佳的 API。选择 `pub use` 会给到咱们在内部组织代码箱方式上的灵活性，并解除了内部结构与呈现给代码箱用户的组织结构的耦合。请查看咱们曾安装的代码箱代码，来发现他们的内部结构，是否不同于其公开 API。 +创建有用的公开 API 结构，与其说是一门科学，不如说是一门艺术，而咱们可不断迭代，找到最适合用户的 API。选择 `pub use` 赋予了咱们在内部组织代码箱方式上的灵活性，并解耦了内部结构与呈现给用户的结构。请查看咱们已安装的一些代码箱的代码，看看发现他们的内部结构是否与其公开 API 有所不同。 ## 建立 Crates.io 帐号 diff --git a/src/images/14-02.png b/src/images/14-02.png index 46b1796..163c52a 100644 Binary files a/src/images/14-02.png and b/src/images/14-02.png differ diff --git a/src/images/14-03.png b/src/images/14-03.png index 915ba4b..ca92f23 100644 Binary files a/src/images/14-03.png and b/src/images/14-03.png differ diff --git a/src/images/14-04.png b/src/images/14-04.png index e804ecb..2ed84af 100644 Binary files a/src/images/14-04.png and b/src/images/14-04.png differ