Merge pull request #242 from not-my-profile/link-cargo-book

doc: Link the Cargo Book in the doc comments of the Package struct

src/lib.rs

@@ -289,24 +289,26 @@ pub struct DepKindInfo {
 /// Each [`target`][Package::targets] of a `Package` will be built as a crate.
 /// For more information, see <https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html>.
 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<String>,
     /// An opaque identifier for a package
     pub id: PackageId,
     /// The source of the package, e.g.
     /// crates.io or `None` for local projects.
     pub source: Option<Source>,
-    /// 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<String>,
     /// List of dependencies of this particular package
     pub dependencies: Vec<Dependency>,
-    /// 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<String>,
+    /// 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<Utf8PathBuf>,
@@ -316,32 +318,33 @@ pub struct Package {
     pub features: BTreeMap<String, Vec<String>>,
     /// 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<String>,
-    /// 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<String>,
-    /// 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<Utf8PathBuf>,
-    /// 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<String>,
-    /// 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<String>,
-    /// 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<String>,
-    /// 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<String>,
-    /// 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<Vec<String>>,
+    /// 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<String>,
+    /// 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.