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();