docs: Clean up doc comments (#14823)

### What does this PR try to resolve?

I'm experimenting with API changes in Cargo and wanted to make it easier
to find doc comments that need updating. I didn't see a lint to help
with this but I did go ahead and apply the result of other documentation
lints.

### How should we test and review this PR?

I've not turned these lints on more generally
- `clippy::doc_markdown` has some false positives we'd need to record in
our config (`SemVer` and `SQLite`)
- `clippy::too_long_first_doc_paragraph` pointed out a doc comment that,
at a quick glance, I didn't see what summary to provide

I also didn't wanted to get this in without making a policy decision of
what lints are enabled.

### Additional information

Author: ehuss

Cargo.lock

@@ -1,7 +1,7 @@
 //! Utility for capturing a global cache last-use database based on the files
 //! on a real-world system.
 //!
-//! This will look in the CARGO_HOME of the current system and record last-use
+//! This will look in the `CARGO_HOME` of the current system and record last-use
 //! data for all files in the cache. This is intended to provide a real-world
 //! example for a benchmark that should be close to what a real set of data
 //! should look like.

benches/benchsuite/src/bin/capture-last-use.rs

@@ -621,7 +621,7 @@ macro_rules! impl_from_tuple_for_inmemorydir {
     };
 }
 
-/// Extend `impl_from_tuple_for_inmemorydir`` to generate for the specified tuple and all smaller
+/// Extend `impl_from_tuple_for_inmemorydir` to generate for the specified tuple and all smaller
 /// tuples
 macro_rules! impl_from_tuples_for_inmemorydir {
     ($var1:ident $path1:ident $data1:ident, $($var:ident $path:ident $data:ident),+) => {

crates/cargo-test-support/src/compare.rs

@@ -5,7 +5,7 @@
 //! with the running container.
 //!
 //! Tests using containers must use `#[cargo_test(container_test)]` to disable
-//! them unless the CARGO_CONTAINER_TESTS environment variable is set.
+//! them unless the `CARGO_CONTAINER_TESTS` environment variable is set.
 
 use cargo_util::ProcessBuilder;
 use std::collections::HashMap;
@@ -36,7 +36,7 @@ pub struct ContainerHandle {
     /// This can only be used on Linux. macOS and Windows docker doesn't allow
     /// direct connection to the container.
     pub ip_address: String,
-    /// Port mappings of container_port to host_port for ports exposed via EXPOSE.
+    /// Port mappings of `container_port` to `host_port` for ports exposed via EXPOSE.
     pub port_mappings: HashMap<u16, u16>,
 }
 

crates/cargo-test-support/src/containers.rs

@@ -3,7 +3,7 @@
 //! Note that cross-testing is very limited. You need to install the
 //! "alternate" target to the host (32-bit for 64-bit hosts or vice-versa).
 //!
-//! Set CFG_DISABLE_CROSS_TESTS=1 environment variable to disable these tests
+//! Set `CFG_DISABLE_CROSS_TESTS=1` environment variable to disable these tests
 //! if you are unable to use the alternate target. Unfortunately 32-bit
 //! support on macOS is going away, so macOS users are out of luck.
 //!

crates/cargo-test-support/src/cross_compile.rs

@@ -890,7 +890,7 @@ impl Execs {
     ///
     /// Prefer [`Execs::with_stdout_data`] where possible.
     /// - `with` cannot be snapshotted
-    /// - The absence of `without`` can either mean success or that the string being looked for
+    /// - The absence of `without` can either mean success or that the string being looked for
     ///   changed.
     ///
     /// </div>
@@ -1565,9 +1565,10 @@ pub fn is_coarse_mtime() -> bool {
     cfg!(target_os = "macos") && is_ci()
 }
 
+/// A way for to increase the cut off for all the time based test.
+///
 /// Some CI setups are much slower then the equipment used by Cargo itself.
 /// Architectures that do not have a modern processor, hardware emulation, etc.
-/// This provides a way for those setups to increase the cut off for all the time based test.
 pub fn slow_cpu_multiplier(main: u64) -> Duration {
     static SLOW_CPU_MULTIPLIER: OnceLock<u64> = OnceLock::new();
     let slow_cpu_multiplier = SLOW_CPU_MULTIPLIER.get_or_init(|| {

crates/cargo-test-support/src/lib.rs

@@ -17,7 +17,7 @@ static CARGO_INTEGRATION_TEST_DIR: &str = "cit";
 static GLOBAL_ROOT: OnceLock<Mutex<Option<PathBuf>>> = OnceLock::new();
 
 /// This is used when running cargo is pre-CARGO_TARGET_TMPDIR
-/// TODO: Remove when CARGO_TARGET_TMPDIR grows old enough.
+/// TODO: Remove when `CARGO_TARGET_TMPDIR` grows old enough.
 fn global_root_legacy() -> PathBuf {
     let mut path = t!(env::current_exe());
     path.pop(); // chop off exe name

crates/cargo-test-support/src/paths.rs

@@ -166,7 +166,7 @@ fn read_new_post(new_path: &Path) -> (Vec<u8>, Vec<u8>) {
 ///
 /// - `expected_crate_name` should be something like `foo-0.0.1.crate`.
 /// - `expected_files` should be a complete list of files in the crate
-///   (relative to expected_crate_name).
+///   (relative to `expected_crate_name`).
 /// - `expected_contents` should be a list of `(file_name, contents)` tuples
 ///   to validate the contents of the given file. Only the listed files will
 ///   be checked (others will be ignored).

crates/cargo-test-support/src/publish.rs

@@ -1680,7 +1680,7 @@ impl<'de> de::Deserialize<'de> for InvalidCargoFeatures {
     }
 }
 
-/// A StringOrVec can be parsed from either a TOML string or array,
+/// This can be parsed from either a TOML string or array,
 /// but is always stored as a vector.
 #[derive(Clone, Debug, Serialize, Eq, PartialEq, PartialOrd, Ord)]
 #[cfg_attr(feature = "unstable-schema", derive(schemars::JsonSchema))]

crates/cargo-util-schemas/src/manifest/mod.rs

@@ -189,7 +189,7 @@ pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> Result<()>
 
 /// Writes a file to disk atomically.
 ///
-/// write_atomic uses tempfile::persist to accomplish atomic writes.
+/// This uses `tempfile::persist` to accomplish atomic writes.
 pub fn write_atomic<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> Result<()> {
     let path = path.as_ref();
 

crates/cargo-util/src/paths.rs

@@ -10,11 +10,11 @@ use std::{
 /// in-process unit testing by rustup.
 pub trait Env {
     /// Return the path to the users home dir, or None if any error occurs:
-    /// see home_inner.
+    /// see `home_inner`.
     fn home_dir(&self) -> Option<PathBuf>;
     /// Return the current working directory.
     fn current_dir(&self) -> io::Result<PathBuf>;
-    /// Get an environment variable, as per std::env::var_os.
+    /// Get an environment variable, as per `std::env::var_os`.
     fn var_os(&self, key: &str) -> Option<OsString>;
 }
 
@@ -47,7 +47,9 @@ pub fn home_dir_with_env(env: &dyn Env) -> Option<PathBuf> {
     env.home_dir()
 }
 
-/// Variant of cargo_home where the environment source is parameterized. This is
+/// Variant of `cargo_home` where the environment source is parameterized.
+///
+/// This is
 /// specifically to support in-process testing scenarios as environment
 /// variables and user home metadata are normally process global state. See the
 /// [`Env`] trait.
@@ -56,10 +58,12 @@ pub fn cargo_home_with_env(env: &dyn Env) -> io::Result<PathBuf> {
     cargo_home_with_cwd_env(env, &cwd)
 }
 
-/// Variant of cargo_home_with_cwd where the environment source is
-/// parameterized. This is specifically to support in-process testing scenarios
+/// Variant of `cargo_home_with_cwd` where the environment source is
+/// parameterized.
+///
+/// This is specifically to support in-process testing scenarios
 /// as environment variables and user home metadata are normally process global
-/// state. See the OsEnv trait.
+/// state. See the `OsEnv` trait.
 pub fn cargo_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result<PathBuf> {
     match env.var_os("CARGO_HOME").filter(|h| !h.is_empty()) {
         Some(home) => {
@@ -76,19 +80,23 @@ pub fn cargo_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result<PathBuf>
     }
 }
 
-/// Variant of cargo_home_with_cwd where the environment source is
-/// parameterized. This is specifically to support in-process testing scenarios
+/// Variant of `cargo_home_with_cwd` where the environment source is
+/// parameterized.
+///
+/// This is specifically to support in-process testing scenarios
 /// as environment variables and user home metadata are normally process global
-/// state. See the OsEnv trait.
+/// state. See the `OsEnv` trait.
 pub fn rustup_home_with_env(env: &dyn Env) -> io::Result<PathBuf> {
     let cwd = env.current_dir()?;
     rustup_home_with_cwd_env(env, &cwd)
 }
 
-/// Variant of cargo_home_with_cwd where the environment source is
-/// parameterized. This is specifically to support in-process testing scenarios
+/// Variant of `cargo_home_with_cwd` where the environment source is
+/// parameterized.
+///
+/// This is specifically to support in-process testing scenarios
 /// as environment variables and user home metadata are normally process global
-/// state. See the OsEnv trait.
+/// state. See the `OsEnv` trait.
 pub fn rustup_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result<PathBuf> {
     match env.var_os("RUSTUP_HOME").filter(|h| !h.is_empty()) {
         Some(home) => {

crates/home/src/env.rs

@@ -24,7 +24,7 @@ pub fn parse_name_and_section(text: &str) -> Result<(&str, u8), Error> {
     Ok((name, section))
 }
 
-/// Extracts the text from a header after Tag::Heading has been received.
+/// Extracts the text from a header after `Tag::Heading` has been received.
 pub fn header_text<'e>(parser: &mut EventIter<'e>) -> Result<CowStr<'e>, Error> {
     let text = match parser.next() {
         Some((Event::Text(t), _range)) => t,

crates/mdman/src/util.rs

@@ -20,9 +20,10 @@ fn log_bits(x: usize) -> usize {
     (num_bits::<usize>() as u32 - x.leading_zeros()) as usize
 }
 
-// At this point is possible to select every version of every package.
-// So we need to mark certain versions as incompatible with each other.
-// We could add a clause not A, not B for all A and B that are incompatible,
+/// At this point is possible to select every version of every package.
+///
+/// So we need to mark certain versions as incompatible with each other.
+/// We could add a clause not A, not B for all A and B that are incompatible,
 fn sat_at_most_one(solver: &mut varisat::Solver<'_>, vars: &[varisat::Var]) {
     if vars.len() <= 1 {
         return;
@@ -327,7 +328,9 @@ fn process_compatible_dep_summaries(
     }
 }
 
-/// Resolution can be reduced to the SAT problem. So this is an alternative implementation
+/// Resolution can be reduced to the SAT problem.
+///
+/// So this is an alternative implementation
 /// of the resolver that uses a SAT library for the hard work. This is intended to be easy to read,
 /// as compared to the real resolver.
 ///

crates/resolver-tests/src/sat.rs

@@ -36,7 +36,7 @@ pub struct DiagnosticSpan {
     /// Is this a "primary" span -- meaning the point, or one of the points,
     /// where the error occurred?
     pub is_primary: bool,
-    /// Source text from the start of line_start to the end of line_end.
+    /// Source text from the start of `line_start` to the end of `line_end`.
     pub text: Vec<DiagnosticSpanLine>,
     /// Label that should be placed at this location (if any)
     label: Option<String>,

crates/rustfix/src/diagnostics.rs

@@ -1,6 +1,6 @@
 [package]
 name = "cargo-credential"
-version = "0.4.7"
+version = "0.4.8"
 rust-version.workspace = true
 edition.workspace = true
 license.workspace = true

credential/cargo-credential/Cargo.toml

@@ -211,7 +211,9 @@ pub enum CacheControl {
     Unknown,
 }
 
-/// Credential process JSON protocol version. If the protocol needs to make
+/// Credential process JSON protocol version.
+///
+/// If the protocol needs to make
 /// a breaking change, a new protocol version should be defined (`PROTOCOL_VERSION_2`).
 /// This library should offer support for both protocols if possible, by signaling
 /// in the `CredentialHello` message. Cargo will then choose which protocol to use,

credential/cargo-credential/src/lib.rs

@@ -154,6 +154,7 @@ pub enum MessageFormat {
 }
 
 /// The general "mode" for what to do.
+///
 /// This is used for two purposes. The commands themselves pass this in to
 /// `compile_ws` to tell it the general execution strategy. This influences
 /// the default targets selected. The other use is in the `Unit` struct

src/cargo/core/compiler/build_config.rs

@@ -121,10 +121,10 @@ impl<'a, 'gctx> BuildContext<'a, 'gctx> {
 
     /// Gets the host architecture triple.
     ///
-    /// For example, x86_64-unknown-linux-gnu, would be
-    /// - machine: x86_64,
-    /// - hardware-platform: unknown,
-    /// - operating system: linux-gnu.
+    /// For example, `x86_64-unknown-linux-gnu`, would be
+    /// - machine: `x86_64`,
+    /// - hardware-platform: `unknown`,
+    /// - operating system: `linux-gnu`.
     pub fn host_triple(&self) -> InternedString {
         self.target_data.rustc.host
     }

src/cargo/core/compiler/build_context/mod.rs

@@ -93,7 +93,7 @@ pub struct FileType {
 }
 
 impl FileType {
-    /// The filename for this FileType crated by rustc.
+    /// The filename for this `FileType` crated by rustc.
     pub fn output_filename(&self, target: &Target, metadata: Option<&str>) -> String {
         match metadata {
             Some(metadata) => format!(
@@ -107,7 +107,7 @@ impl FileType {
         }
     }
 
-    /// The filename for this FileType that Cargo should use when "uplifting"
+    /// The filename for this `FileType` that Cargo should use when "uplifting"
     /// it to the destination directory.
     pub fn uplift_filename(&self, target: &Target) -> String {
         let name = match target.binary_filename() {
@@ -513,10 +513,10 @@ impl TargetInfo {
         parse_crate_type(crate_type, &process, output, error, &mut output.lines())
     }
 
-    /// Returns all the file types generated by rustc for the given mode/target_kind.
+    /// Returns all the file types generated by rustc for the given `mode`/`target_kind`.
     ///
     /// The first value is a Vec of file types generated, the second value is
-    /// a list of CrateTypes that are not supported by the given target.
+    /// a list of `CrateTypes` that are not supported by the given target.
     pub fn rustc_outputs(
         &self,
         mode: CompileMode,

src/cargo/core/compiler/build_context/target_info.rs

@@ -1,8 +1,8 @@
 //! A graph-like structure used to represent the rustc commands to build the package and the
 //! interdependencies between them.
 //!
-//! The BuildPlan structure is used to store the dependency graph of a dry run so that it can be
-//! shared with an external build system. Each Invocation in the BuildPlan comprises a single
+//! The `BuildPlan` structure is used to store the dependency graph of a dry run so that it can be
+//! shared with an external build system. Each Invocation in the `BuildPlan` comprises a single
 //! subprocess and defines the build environment, the outputs produced by the subprocess, and the
 //! dependencies on other Invocations.
 

src/cargo/core/compiler/build_plan.rs

@@ -175,7 +175,7 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
     ///
     /// See [`Metadata`] and [`fingerprint`] module for more.
     ///
-    /// [`fingerprint`]: ../../fingerprint/index.html#fingerprints-and-metadata
+    /// [`fingerprint`]: super::super::fingerprint#fingerprints-and-metadata
     pub fn metadata(&self, unit: &Unit) -> Metadata {
         self.metas[unit].meta_hash
     }
@@ -328,7 +328,7 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
         self.layout(unit.kind).build().join(dir)
     }
 
-    /// Returns the "OUT_DIR" directory for running a build script.
+    /// Returns the "`OUT_DIR`" directory for running a build script.
     /// `/path/to/target/{debug,release}/build/PKG-HASH/out`
     pub fn build_script_out_dir(&self, unit: &Unit) -> PathBuf {
         self.build_script_run_dir(unit).join("out")
@@ -375,7 +375,7 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
             .map(Arc::clone)
     }
 
-    /// Returns the path where the output for the given unit and FileType
+    /// Returns the path where the output for the given unit and `FileType`
     /// should be uplifted to.
     ///
     /// Returns `None` if the unit shouldn't be uplifted (for example, a

src/cargo/core/compiler/build_runner/compilation_files.rs

@@ -80,7 +80,7 @@ pub struct BuildRunner<'a, 'gctx> {
     pub lto: HashMap<Unit, Lto>,
 
     /// Map of Doc/Docscrape units to metadata for their -Cmetadata flag.
-    /// See Context::find_metadata_units for more details.
+    /// See `Context::find_metadata_units` for more details.
     pub metadata_for_doc_units: HashMap<Unit, Metadata>,
 
     /// Set of metadata of Docscrape units that fail before completion, e.g.
@@ -155,7 +155,7 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
     ///
     /// See [`ops::cargo_compile`] for a higher-level view of the compile process.
     ///
-    /// [`ops::cargo_compile`]: ../../../ops/cargo_compile/index.html
+    /// [`ops::cargo_compile`]: crate::ops::cargo_compile
     #[tracing::instrument(skip_all)]
     pub fn compile(mut self, exec: &Arc<dyn Executor>) -> CargoResult<Compilation<'gctx>> {
         // A shared lock is held during the duration of the build since rustc
@@ -415,7 +415,7 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
         &self.bcx.unit_graph[unit]
     }
 
-    /// Returns the RunCustomBuild Unit associated with the given Unit.
+    /// Returns the `RunCustomBuild` Unit associated with the given Unit.
     ///
     /// If the package does not have a build script, this returns None.
     pub fn find_build_script_unit(&self, unit: &Unit) -> Option<Unit> {
@@ -431,7 +431,7 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
             .map(|unit_dep| unit_dep.unit.clone())
     }
 
-    /// Returns the metadata hash for the RunCustomBuild Unit associated with
+    /// Returns the metadata hash for the `RunCustomBuild` Unit associated with
     /// the given unit.
     ///
     /// If the package does not have a build script, this returns None.
@@ -440,7 +440,7 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
         Some(self.get_run_build_script_metadata(&script_unit))
     }
 
-    /// Returns the metadata hash for a RunCustomBuild unit.
+    /// Returns the metadata hash for a `RunCustomBuild` unit.
     pub fn get_run_build_script_metadata(&self, unit: &Unit) -> Metadata {
         assert!(unit.mode.is_run_custom_build());
         self.files().metadata(unit)