Auto merge of #9468 - PaulDance:fix-rustdoc-warnings, r=ehuss

Fix rustdoc warnings

Change some small parts of the unit documentation in order to resolve warnings emitted when running `cargo doc` from the root of this project. It should help reduce the noise when checking that new or updated documentation builds correctly.

See the commit messages for details about the modifications themselves, although they should be rather simple.

Cheers,
Paul.

crates/cargo-util/src/paths.rs

@@ -161,7 +161,7 @@ pub fn write<P: AsRef<Path>, 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<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> Result<()> {
     (|| -> Result<()> {
@@ -184,7 +184,7 @@ pub fn write_if_changed<P: AsRef<Path>, 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<()> {

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

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 {
@@ -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.