From cb0b9ec045247259cc87febcdcd9604d2e7fc7fb Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Thu, 20 Jul 2023 10:17:30 +0200 Subject: [PATCH] doc: Link the Cargo Book in the doc comments of the Package struct --- src/lib.rs | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index c222c130..a1d586ac 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -289,11 +289,12 @@ pub struct DepKindInfo { /// Each [`target`][Package::targets] of a `Package` will be built as a crate. /// For more information, see . pub struct Package { - /// Name as given in the `Cargo.toml` + /// The [`name` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) as given in the `Cargo.toml` + // (We say "given in" instead of "specified in" since the `name` key cannot be inherited from the workspace.) pub name: String, - /// Version given in the `Cargo.toml` + /// The [`version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field) as specified in the `Cargo.toml` pub version: Version, - /// Authors given in the `Cargo.toml` + /// The [`authors` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-authors-field) as specified in the `Cargo.toml` #[serde(default)] pub authors: Vec, /// An opaque identifier for a package @@ -301,12 +302,13 @@ pub struct Package { /// The source of the package, e.g. /// crates.io or `None` for local projects. pub source: Option, - /// Description as given in the `Cargo.toml` + /// The [`description` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-description-field) as specified in the `Cargo.toml` pub description: Option, /// List of dependencies of this particular package pub dependencies: Vec, - /// License as given in the `Cargo.toml` + /// The [`license` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields) as specified in the `Cargo.toml` pub license: Option, + /// The [`license-file` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields) as specified in the `Cargo.toml`. /// If the package is using a nonstandard license, this key may be specified instead of /// `license`, and must point to a file relative to the manifest. pub license_file: Option, @@ -316,32 +318,33 @@ pub struct Package { pub features: BTreeMap>, /// Path containing the `Cargo.toml` pub manifest_path: Utf8PathBuf, - /// Categories as given in the `Cargo.toml` + /// The [`categories` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-categories-field) as specified in the `Cargo.toml` #[serde(default)] pub categories: Vec, - /// Keywords as given in the `Cargo.toml` + /// The [`keywords` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-keywords-field) as specified in the `Cargo.toml` #[serde(default)] pub keywords: Vec, - /// Readme as given in the `Cargo.toml` + /// The [`readme` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-readme-field) as specified in the `Cargo.toml` pub readme: Option, - /// Repository as given in the `Cargo.toml` + /// The [`repository` URL](https://doc.rust-lang.org/cargo/reference/manifest.html#the-repository-field) as specified in the `Cargo.toml` // can't use `url::Url` because that requires a more recent stable compiler pub repository: Option, - /// Homepage as given in the `Cargo.toml` + /// The [`homepage` URL](https://doc.rust-lang.org/cargo/reference/manifest.html#the-homepage-field) as specified in the `Cargo.toml`. /// /// On versions of cargo before 1.49, this will always be [`None`]. pub homepage: Option, - /// Documentation URL as given in the `Cargo.toml` + /// The [`documentation` URL](https://doc.rust-lang.org/cargo/reference/manifest.html#the-documentation-field) as specified in the `Cargo.toml`. /// /// On versions of cargo before 1.49, this will always be [`None`]. pub documentation: Option, - /// Default Rust edition for the package + /// The default Rust edition for the package (either what's specified in the [`edition` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field) + /// or defaulting to [`Edition::E2015`]). /// /// Beware that individual targets may specify their own edition in /// [`Target::edition`]. #[serde(default)] pub edition: Edition, - /// Contents of the free form package.metadata section + /// Contents of the free form [`package.metadata` section](https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table). /// /// This contents can be serialized to a struct using serde: /// @@ -368,16 +371,19 @@ pub struct Package { pub metadata: serde_json::Value, /// The name of a native library the package is linking to. pub links: Option, - /// List of registries to which this package may be published. + /// List of registries to which this package may be published (derived from the [`publish` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-publish-field)). /// /// Publishing is unrestricted if `None`, and forbidden if the `Vec` is empty. /// /// This is always `None` if running with a version of Cargo older than 1.39. pub publish: Option>, + /// The [`default-run` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-default-run-field) as given in the `Cargo.toml` + // (We say "given in" instead of "specified in" since the `default-run` key cannot be inherited from the workspace.) /// The default binary to run by `cargo run`. /// /// This is always `None` if running with a version of Cargo older than 1.55. pub default_run: Option, + /// The [`rust-version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) as specified in the `Cargo.toml`. /// The minimum supported Rust version of this package. /// /// This is always `None` if running with a version of Cargo older than 1.58.