docs: Surround identifiers in backticks

This was mostly done by clippy via `clippy::doc_markdown`.
I then reviewed it to fix words that shouldn't have it or where `--fix`
put the backtick in the wrong location.

Author: epage

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

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

crates/cargo-test-support/src/compare.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/containers.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/cross_compile.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/lib.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>

crates/cargo-test-support/src/paths.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/publish.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-util-schemas/src/manifest/mod.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/src/paths.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/home/src/env.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,7 @@ 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 +56,10 @@ 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
+/// 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 +76,19 @@ 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
+/// 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
+/// 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/mdman/src/util.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/rustfix/src/diagnostics.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>,

src/cargo/core/compiler/build_context/mod.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/target_info.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_plan.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_runner/compilation_files.rs

@@ -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/mod.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.
@@ -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)

src/cargo/core/compiler/compilation.rs

@@ -81,7 +81,7 @@ pub struct Compilation<'gctx> {
     /// All directories for the output of native build commands.
     ///
     /// This is currently used to drive some entries which are added to the
-    /// LD_LIBRARY_PATH as appropriate.
+    /// `LD_LIBRARY_PATH` as appropriate.
     ///
     /// The order should be deterministic.
     pub native_dirs: BTreeSet<PathBuf>,
@@ -113,10 +113,10 @@ pub struct Compilation<'gctx> {
 
     /// Rustc process to be used by default
     rustc_process: ProcessBuilder,
-    /// Rustc process to be used for workspace crates instead of rustc_process
+    /// Rustc process to be used for workspace crates instead of `rustc_process`
     rustc_workspace_wrapper_process: ProcessBuilder,
-    /// Optional rustc process to be used for primary crates instead of either rustc_process or
-    /// rustc_workspace_wrapper_process
+    /// Optional rustc process to be used for primary crates instead of either `rustc_process` or
+    /// `rustc_workspace_wrapper_process`
     primary_rustc_process: Option<ProcessBuilder>,
 
     target_runners: HashMap<CompileKind, Option<(PathBuf, Vec<String>)>>,
@@ -403,7 +403,7 @@ impl<'gctx> Compilation<'gctx> {
     }
 }
 
-/// Prepares a rustc_tool process with additional environment variables
+/// Prepares a `rustc_tool` process with additional environment variables
 /// that are only relevant in a context that has a unit
 fn fill_rustc_tool_env(mut cmd: ProcessBuilder, unit: &Unit) -> ProcessBuilder {
     if unit.target.is_executable() {

src/cargo/core/compiler/custom_build.rs

@@ -111,7 +111,7 @@ pub struct BuildOutput {
 /// inserted during `build_map`. The rest of the entries are added
 /// immediately after each build script runs.
 ///
-/// The `Metadata` is the unique metadata hash for the RunCustomBuild Unit of
+/// The `Metadata` is the unique metadata hash for the `RunCustomBuild` Unit of
 /// the package. It needs a unique key, since the build script can be run
 /// multiple times with different profiles or features. We can't embed a
 /// `Unit` because this structure needs to be shareable between threads.
@@ -150,7 +150,7 @@ pub struct BuildScripts {
     /// This is the set of transitive dependencies that are host-only
     /// (proc-macro, plugin, build-dependency) that contain a build script.
     /// Any `BuildOutput::library_paths` path relative to `target` will be
-    /// added to LD_LIBRARY_PATH so that the compiler can find any dynamic
+    /// added to `LD_LIBRARY_PATH` so that the compiler can find any dynamic
     /// libraries a build script may have generated.
     pub plugins: BTreeSet<(PackageId, Metadata)>,
 }

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

@@ -69,13 +69,13 @@
 //! `cargo rustc` extra args                   | ✓           | ✓
 //! [`CompileMode`]                            | ✓           | ✓
 //! Target Name                                | ✓           | ✓
-//! TargetKind (bin/lib/etc.)                  | ✓           | ✓
+//! `TargetKind` (bin/lib/etc.)                | ✓           | ✓
 //! Enabled Features                           | ✓           | ✓
 //! Declared Features                          | ✓           |
 //! Immediate dependency’s hashes              | ✓[^1]       | ✓
 //! [`CompileKind`] (host/target)              | ✓           | ✓
-//! __CARGO_DEFAULT_LIB_METADATA[^4]           |             | ✓
-//! package_id                                 |             | ✓
+//! `__CARGO_DEFAULT_LIB_METADATA`[^4]         |             | ✓
+//! `package_id`                               |             | ✓
 //! authors, description, homepage, repo       | ✓           |
 //! Target src path relative to ws             | ✓           |
 //! Target flags (test/bench/for_host/edition) | ✓           |
@@ -84,7 +84,7 @@
 //! RUSTFLAGS/RUSTDOCFLAGS                     | ✓           |
 //! [`Lto`] flags                              | ✓           | ✓
 //! config settings[^5]                        | ✓           |
-//! is_std                                     |             | ✓
+//! `is_std`                                   |             | ✓
 //! `[lints]` table[^6]                        | ✓           |
 //! `[lints.rust.unexpected_cfgs.check-cfg]`   | ✓           |
 //!
@@ -738,7 +738,7 @@ enum LocalFingerprint {
     /// for us to look at. If any of those files are newer than this file then
     /// we need to recompile.
     ///
-    /// If the `checksum` bool is true then the dep_info file is expected to
+    /// If the `checksum` bool is true then the `dep_info` file is expected to
     /// contain file checksums instead of file mtimes.
     CheckDepInfo { dep_info: PathBuf, checksum: bool },
 

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

@@ -151,7 +151,7 @@ use crate::util::{DependencyQueue, GlobalContext, Progress, ProgressStyle, Queue
 
 /// This structure is backed by the `DependencyQueue` type and manages the
 /// queueing of compilation steps for each package. Packages enqueue units of
-/// work and then later on the entire graph is converted to DrainState and
+/// work and then later on the entire graph is converted to `DrainState` and
 /// executed.
 pub struct JobQueue<'gctx> {
     queue: DependencyQueue<Unit, Artifact, Job>,
@@ -163,7 +163,7 @@ pub struct JobQueue<'gctx> {
 /// actual compilation step of each package. Packages enqueue units of work and
 /// then later on the entire graph is processed and compiled.
 ///
-/// It is created from JobQueue when we have fully assembled the crate graph
+/// It is created from `JobQueue` when we have fully assembled the crate graph
 /// (i.e., all package dependencies are known).
 struct DrainState<'gctx> {
     // This is the length of the DependencyQueue when starting out
@@ -265,9 +265,9 @@ struct ErrorToHandle {
     /// care about individually reporting every thread that it broke; just the
     /// first is enough.
     ///
-    /// The exception where print_always is true is that we do report every
+    /// The exception where `print_always` is true is that we do report every
     /// instance of a rustc invocation that failed with diagnostics. This
-    /// corresponds to errors from Message::Finish.
+    /// corresponds to errors from `Message::Finish`.
     print_always: bool,
 }