From d7122e691e9680accef36b97b1b5f2e0ea4ca7d8 Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sun, 9 May 2021 19:14:52 +0200 Subject: [PATCH 1/4] Remove rustdoc warnings for core::features Link `CliUnstable::add` just to `CliUnstable` instead. Signed-off-by: Paul Mabileau --- src/cargo/core/features.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index 56321cdde80..0e459d4db83 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -62,7 +62,7 @@ //! //! 1. Add the option to the [`CliUnstable`] struct below. Flags can take an //! optional value if you want. -//! 2. Update the [`CliUnstable::add`] function to parse the flag. +//! 2. Update the [`CliUnstable::add`][CliUnstable] function to parse the flag. //! 3. Wherever the new functionality is implemented, call //! [`Config::cli_unstable`][crate::util::config::Config::cli_unstable] to //! get an instance of `CliUnstable` and check if the option has been @@ -81,8 +81,8 @@ //! macro below. //! 2. `-Z unstable-options`: Find the call to `fail_if_stable_opt` and //! remove it. Be sure to update the man pages if necessary. -//! 3. `-Z` flag: Change the parsing code in [`CliUnstable::add`] to call -//! `stabilized_warn` or `stabilized_err` and remove the field from +//! 3. `-Z` flag: Change the parsing code in [`CliUnstable::add`][CliUnstable] +//! to call `stabilized_warn` or `stabilized_err` and remove the field from //! `CliUnstable. Remove the `(unstable)` note in the clap help text if //! necessary. //! 2. Remove `masquerade_as_nightly_cargo` from any tests, and remove From acf157690a505d7f8e3ad9f460be8e1d147cbcfd Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sun, 9 May 2021 19:25:45 +0200 Subject: [PATCH 2/4] Fix rustdoc warnings for RegistrySource and RegistryData Inline the link targets directly in the text. Signed-off-by: Paul Mabileau --- src/cargo/sources/registry/mod.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/cargo/sources/registry/mod.rs b/src/cargo/sources/registry/mod.rs index 334053694bd..a5c85a553cc 100644 --- a/src/cargo/sources/registry/mod.rs +++ b/src/cargo/sources/registry/mod.rs @@ -189,8 +189,8 @@ const VERSION_TEMPLATE: &str = "{version}"; const PREFIX_TEMPLATE: &str = "{prefix}"; const LOWER_PREFIX_TEMPLATE: &str = "{lowerprefix}"; -/// A "source" for a [local](local::LocalRegistry) or -/// [remote](remote::RemoteRegistry) registry. +/// A "source" for a local (see `local::LocalRegistry`) or remote (see +/// `remote::RemoteRegistry`) registry. /// /// This contains common functionality that is shared between the two registry /// kinds, with the registry-specific logic implemented as part of the @@ -415,8 +415,8 @@ impl<'a> RegistryDependency<'a> { } } -/// An abstract interface to handle both a [local](local::LocalRegistry) and -/// [remote](remote::RemoteRegistry) registry. +/// An abstract interface to handle both a local (see `local::LocalRegistry`) +/// and remote (see `remote::RemoteRegistry`) registry. /// /// This allows [`RegistrySource`] to abstractly handle both registry kinds. pub trait RegistryData { From 2daf97c2e5aa016c4379a307d3b537917b7ef3e3 Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sun, 9 May 2021 19:37:13 +0200 Subject: [PATCH 3/4] Resolve doc warnings for RegistryData Specify `Self::finish_download` instead of just `finish_download` and link to `crate::core::package::Downloads` instead of `Download` as `Downloads` is the public one, does the actual stuff and `Download` only stores data. Signed-off-by: Paul Mabileau --- src/cargo/sources/registry/mod.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/cargo/sources/registry/mod.rs b/src/cargo/sources/registry/mod.rs index a5c85a553cc..7b08cb3bb72 100644 --- a/src/cargo/sources/registry/mod.rs +++ b/src/cargo/sources/registry/mod.rs @@ -460,9 +460,9 @@ pub trait RegistryData { /// Despite the name, this doesn't actually download anything. If the /// `.crate` is already downloaded, then it returns [`MaybeLock::Ready`]. /// If it hasn't been downloaded, then it returns [`MaybeLock::Download`] - /// which contains the URL to download. The [`crate::core::package::Download`] + /// which contains the URL to download. The [`crate::core::package::Downloads`] /// system handles the actual download process. After downloading, it - /// calls [`finish_download`] to save the downloaded file. + /// calls [`Self::finish_download`] to save the downloaded file. /// /// `checksum` is currently only used by local registries to verify the /// file contents (because local registries never actually download @@ -474,7 +474,7 @@ pub trait RegistryData { /// Finish a download by saving a `.crate` file to disk. /// - /// After [`crate::core::package::Download`] has finished a download, + /// After [`crate::core::package::Downloads`] has finished a download, /// it will call this to save the `.crate` file. This is only relevant /// for remote registries. This should validate the checksum and save /// the given data to the on-disk cache. From 9ea1cbdedac0bfd127a58637121c39ce7c7eed0c Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sun, 9 May 2021 19:47:08 +0200 Subject: [PATCH 4/4] Fix doc warnings for cargo-util::paths Add parentheses to disambiguate from `write!`. Signed-off-by: Paul Mabileau --- crates/cargo-util/src/paths.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/cargo-util/src/paths.rs b/crates/cargo-util/src/paths.rs index ea39273a82d..60be12e455f 100644 --- a/crates/cargo-util/src/paths.rs +++ b/crates/cargo-util/src/paths.rs @@ -161,7 +161,7 @@ pub fn write, C: AsRef<[u8]>>(path: P, contents: C) -> Result<()> .with_context(|| format!("failed to write `{}`", path.display())) } -/// Equivalent to [`write`], but does not write anything if the file contents +/// Equivalent to [`write()`], but does not write anything if the file contents /// are identical to the given contents. pub fn write_if_changed, C: AsRef<[u8]>>(path: P, contents: C) -> Result<()> { (|| -> Result<()> { @@ -184,7 +184,7 @@ pub fn write_if_changed, C: AsRef<[u8]>>(path: P, contents: C) -> Ok(()) } -/// Equivalent to [`write`], but appends to the end instead of replacing the +/// Equivalent to [`write()`], but appends to the end instead of replacing the /// contents. pub fn append(path: &Path, contents: &[u8]) -> Result<()> { (|| -> Result<()> {