From 179c516f9b8d655ea6b42ee3a48e0501a3d3d691 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 15 Nov 2024 09:33:14 -0600 Subject: [PATCH 1/4] chore: Bump cargo-credential --- Cargo.lock | 2 +- credential/cargo-credential/Cargo.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 7d2abf48a8f..2a167643abe 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -387,7 +387,7 @@ dependencies = [ [[package]] name = "cargo-credential" -version = "0.4.7" +version = "0.4.8" dependencies = [ "anyhow", "libc", diff --git a/credential/cargo-credential/Cargo.toml b/credential/cargo-credential/Cargo.toml index b3da12d3938..713fa41b841 100644 --- a/credential/cargo-credential/Cargo.toml +++ b/credential/cargo-credential/Cargo.toml @@ -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 From 0b281678c3853d3f73e58f32b1860e770fdc4b95 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 14 Nov 2024 19:37:45 -0600 Subject: [PATCH 2/4] docs: Turn relative links to intra-doc links --- src/cargo/core/compiler/build_runner/compilation_files.rs | 2 +- src/cargo/core/compiler/build_runner/mod.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cargo/core/compiler/build_runner/compilation_files.rs b/src/cargo/core/compiler/build_runner/compilation_files.rs index 667cf0379e0..0dda1958069 100644 --- a/src/cargo/core/compiler/build_runner/compilation_files.rs +++ b/src/cargo/core/compiler/build_runner/compilation_files.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 } diff --git a/src/cargo/core/compiler/build_runner/mod.rs b/src/cargo/core/compiler/build_runner/mod.rs index 32651e72a8c..595676cc6ab 100644 --- a/src/cargo/core/compiler/build_runner/mod.rs +++ b/src/cargo/core/compiler/build_runner/mod.rs @@ -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) -> CargoResult> { // A shared lock is held during the duration of the build since rustc From 878caf7447dddb63aecdad80a467f56398b5470a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 14 Nov 2024 19:42:33 -0600 Subject: [PATCH 3/4] 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. --- benches/benchsuite/src/bin/capture-last-use.rs | 2 +- crates/cargo-test-support/src/compare.rs | 2 +- crates/cargo-test-support/src/containers.rs | 4 ++-- crates/cargo-test-support/src/cross_compile.rs | 2 +- crates/cargo-test-support/src/lib.rs | 2 +- crates/cargo-test-support/src/paths.rs | 2 +- crates/cargo-test-support/src/publish.rs | 2 +- crates/cargo-util-schemas/src/manifest/mod.rs | 2 +- crates/cargo-util/src/paths.rs | 2 +- crates/home/src/env.rs | 18 +++++++++--------- crates/mdman/src/util.rs | 2 +- crates/rustfix/src/diagnostics.rs | 2 +- src/cargo/core/compiler/build_context/mod.rs | 8 ++++---- .../core/compiler/build_context/target_info.rs | 8 ++++---- src/cargo/core/compiler/build_plan.rs | 4 ++-- .../compiler/build_runner/compilation_files.rs | 4 ++-- src/cargo/core/compiler/build_runner/mod.rs | 8 ++++---- src/cargo/core/compiler/compilation.rs | 10 +++++----- src/cargo/core/compiler/custom_build.rs | 4 ++-- src/cargo/core/compiler/fingerprint/mod.rs | 10 +++++----- src/cargo/core/compiler/job_queue/mod.rs | 8 ++++---- src/cargo/core/compiler/timings.rs | 2 +- src/cargo/core/compiler/unit_dependencies.rs | 2 +- src/cargo/core/features.rs | 2 +- src/cargo/core/global_cache_tracker.rs | 2 +- src/cargo/core/package.rs | 2 +- src/cargo/core/profiles.rs | 8 ++++---- src/cargo/core/resolver/features.rs | 14 +++++++------- src/cargo/core/resolver/resolve.rs | 2 +- src/cargo/core/resolver/types.rs | 4 ++-- src/cargo/core/source_id.rs | 8 ++++---- src/cargo/core/summary.rs | 4 ++-- src/cargo/core/workspace.rs | 2 +- src/cargo/ops/cargo_add/mod.rs | 2 +- src/cargo/ops/cargo_compile/mod.rs | 2 +- src/cargo/ops/cargo_new.rs | 4 ++-- src/cargo/ops/cargo_update.rs | 2 +- .../ops/common_for_install_and_uninstall.rs | 8 ++++---- src/cargo/ops/registry/mod.rs | 4 ++-- src/cargo/ops/tree/graph.rs | 6 +++--- src/cargo/sources/git/known_hosts.rs | 8 ++++---- src/cargo/sources/git/source.rs | 2 +- src/cargo/sources/registry/index/mod.rs | 2 +- src/cargo/sources/registry/mod.rs | 2 +- src/cargo/util/auth/mod.rs | 2 +- src/cargo/util/command_prelude.rs | 2 +- src/cargo/util/context/de.rs | 6 +++--- src/cargo/util/context/mod.rs | 10 +++++----- src/cargo/util/context/path.rs | 2 +- src/cargo/util/dependency_queue.rs | 4 ++-- src/cargo/util/rustc.rs | 4 ++-- src/cargo/util/semver_ext.rs | 2 +- src/cargo/util/toml_mut/dependency.rs | 6 +++--- tests/testsuite/cfg.rs | 2 +- tests/testsuite/collisions.rs | 2 +- tests/testsuite/fix_n_times.rs | 2 +- tests/testsuite/global_cache_tracker.rs | 4 ++-- tests/testsuite/https.rs | 4 ++-- tests/testsuite/ssh.rs | 4 ++-- 59 files changed, 128 insertions(+), 128 deletions(-) diff --git a/benches/benchsuite/src/bin/capture-last-use.rs b/benches/benchsuite/src/bin/capture-last-use.rs index dc226109baa..ceace090401 100644 --- a/benches/benchsuite/src/bin/capture-last-use.rs +++ b/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. diff --git a/crates/cargo-test-support/src/compare.rs b/crates/cargo-test-support/src/compare.rs index d1c06090df0..b8b55483b08 100644 --- a/crates/cargo-test-support/src/compare.rs +++ b/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),+) => { diff --git a/crates/cargo-test-support/src/containers.rs b/crates/cargo-test-support/src/containers.rs index 4ce6e1d5048..d0277d071fe 100644 --- a/crates/cargo-test-support/src/containers.rs +++ b/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, } diff --git a/crates/cargo-test-support/src/cross_compile.rs b/crates/cargo-test-support/src/cross_compile.rs index beda6616550..10af51097f1 100644 --- a/crates/cargo-test-support/src/cross_compile.rs +++ b/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. //! diff --git a/crates/cargo-test-support/src/lib.rs b/crates/cargo-test-support/src/lib.rs index e736f0712a2..fcbbed26562 100644 --- a/crates/cargo-test-support/src/lib.rs +++ b/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. /// /// diff --git a/crates/cargo-test-support/src/paths.rs b/crates/cargo-test-support/src/paths.rs index e9d51502aad..622fe633424 100644 --- a/crates/cargo-test-support/src/paths.rs +++ b/crates/cargo-test-support/src/paths.rs @@ -17,7 +17,7 @@ static CARGO_INTEGRATION_TEST_DIR: &str = "cit"; static GLOBAL_ROOT: OnceLock>> = 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 diff --git a/crates/cargo-test-support/src/publish.rs b/crates/cargo-test-support/src/publish.rs index e6adac7d048..f6fde1b9805 100644 --- a/crates/cargo-test-support/src/publish.rs +++ b/crates/cargo-test-support/src/publish.rs @@ -166,7 +166,7 @@ fn read_new_post(new_path: &Path) -> (Vec, Vec) { /// /// - `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). diff --git a/crates/cargo-util-schemas/src/manifest/mod.rs b/crates/cargo-util-schemas/src/manifest/mod.rs index 0db29ad492b..efb71d8ceac 100644 --- a/crates/cargo-util-schemas/src/manifest/mod.rs +++ b/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))] diff --git a/crates/cargo-util/src/paths.rs b/crates/cargo-util/src/paths.rs index fc10c5912d9..5d7e3c5a681 100644 --- a/crates/cargo-util/src/paths.rs +++ b/crates/cargo-util/src/paths.rs @@ -189,7 +189,7 @@ pub fn write, 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, C: AsRef<[u8]>>(path: P, contents: C) -> Result<()> { let path = path.as_ref(); diff --git a/crates/home/src/env.rs b/crates/home/src/env.rs index 49fea54220c..13bc17c6eb8 100644 --- a/crates/home/src/env.rs +++ b/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; /// Return the current working directory. fn current_dir(&self) -> io::Result; - /// 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; } @@ -47,7 +47,7 @@ pub fn home_dir_with_env(env: &dyn Env) -> Option { 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 { 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 { 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 } } -/// 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 { 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 { match env.var_os("RUSTUP_HOME").filter(|h| !h.is_empty()) { Some(home) => { diff --git a/crates/mdman/src/util.rs b/crates/mdman/src/util.rs index ed4b61c4b58..0a23ce68766 100644 --- a/crates/mdman/src/util.rs +++ b/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, Error> { let text = match parser.next() { Some((Event::Text(t), _range)) => t, diff --git a/crates/rustfix/src/diagnostics.rs b/crates/rustfix/src/diagnostics.rs index ad1899b2cc8..62575da0117 100644 --- a/crates/rustfix/src/diagnostics.rs +++ b/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, /// Label that should be placed at this location (if any) label: Option, diff --git a/src/cargo/core/compiler/build_context/mod.rs b/src/cargo/core/compiler/build_context/mod.rs index 1bc25d12c19..8fbf05478e9 100644 --- a/src/cargo/core/compiler/build_context/mod.rs +++ b/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 } diff --git a/src/cargo/core/compiler/build_context/target_info.rs b/src/cargo/core/compiler/build_context/target_info.rs index f36fc173bcc..296077589d4 100644 --- a/src/cargo/core/compiler/build_context/target_info.rs +++ b/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, diff --git a/src/cargo/core/compiler/build_plan.rs b/src/cargo/core/compiler/build_plan.rs index d116c07b5be..ad3e65625eb 100644 --- a/src/cargo/core/compiler/build_plan.rs +++ b/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. diff --git a/src/cargo/core/compiler/build_runner/compilation_files.rs b/src/cargo/core/compiler/build_runner/compilation_files.rs index 0dda1958069..042bc9bb296 100644 --- a/src/cargo/core/compiler/build_runner/compilation_files.rs +++ b/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 diff --git a/src/cargo/core/compiler/build_runner/mod.rs b/src/cargo/core/compiler/build_runner/mod.rs index 595676cc6ab..af8c0a7e4a1 100644 --- a/src/cargo/core/compiler/build_runner/mod.rs +++ b/src/cargo/core/compiler/build_runner/mod.rs @@ -80,7 +80,7 @@ pub struct BuildRunner<'a, 'gctx> { pub lto: HashMap, /// 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, /// 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 { @@ -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) diff --git a/src/cargo/core/compiler/compilation.rs b/src/cargo/core/compiler/compilation.rs index 39f0f9f7241..372a0a5694d 100644 --- a/src/cargo/core/compiler/compilation.rs +++ b/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, @@ -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, target_runners: HashMap)>>, @@ -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() { diff --git a/src/cargo/core/compiler/custom_build.rs b/src/cargo/core/compiler/custom_build.rs index 4ee788df573..fce9c96d3bf 100644 --- a/src/cargo/core/compiler/custom_build.rs +++ b/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)>, } diff --git a/src/cargo/core/compiler/fingerprint/mod.rs b/src/cargo/core/compiler/fingerprint/mod.rs index 64a50edb69d..d994830c630 100644 --- a/src/cargo/core/compiler/fingerprint/mod.rs +++ b/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 }, diff --git a/src/cargo/core/compiler/job_queue/mod.rs b/src/cargo/core/compiler/job_queue/mod.rs index 91f977f7d6b..c8df3f2be02 100644 --- a/src/cargo/core/compiler/job_queue/mod.rs +++ b/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, @@ -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, } diff --git a/src/cargo/core/compiler/timings.rs b/src/cargo/core/compiler/timings.rs index 05d37632e5d..ec6e7741e31 100644 --- a/src/cargo/core/compiler/timings.rs +++ b/src/cargo/core/compiler/timings.rs @@ -567,7 +567,7 @@ impl<'gctx> Timings<'gctx> { } impl UnitTime { - /// Returns the codegen time as (rmeta_time, codegen_time, percent of total) + /// Returns the codegen time as (`rmeta_time`, `codegen_time`, percent of total) fn codegen_time(&self) -> Option<(f64, f64, f64)> { self.rmeta_time.map(|rmeta_time| { let ctime = self.duration - rmeta_time; diff --git a/src/cargo/core/compiler/unit_dependencies.rs b/src/cargo/core/compiler/unit_dependencies.rs index 59e356fc682..c42be2dd839 100644 --- a/src/cargo/core/compiler/unit_dependencies.rs +++ b/src/cargo/core/compiler/unit_dependencies.rs @@ -199,7 +199,7 @@ fn attach_std_deps( } /// Compute all the dependencies of the given root units. -/// The result is stored in state.unit_dependencies. +/// The result is stored in `state.unit_dependencies`. fn deps_of_roots(roots: &[Unit], state: &mut State<'_, '_>) -> CargoResult<()> { for unit in roots.iter() { // Dependencies of tests/benches should not have `panic` set. diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index 07a86640a8f..8bce51535f8 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -137,7 +137,7 @@ pub const SEE_CHANNELS: &str = "See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more information \ about Rust release channels."; -/// Value of [`allow-features`](CliUnstable::allow_features] +/// Value of [`allow-features`](CliUnstable::allow_features) pub type AllowFeatures = BTreeSet; /// The edition of the compiler ([RFC 2052]) diff --git a/src/cargo/core/global_cache_tracker.rs b/src/cargo/core/global_cache_tracker.rs index b6cb7a60fdb..1a72b3a1f72 100644 --- a/src/cargo/core/global_cache_tracker.rs +++ b/src/cargo/core/global_cache_tracker.rs @@ -1020,7 +1020,7 @@ impl GlobalCacheTracker { Ok(()) } - /// Adds paths to delete from either registry_crate or registry_src whose + /// Adds paths to delete from either `registry_crate` or `registry_src` whose /// last use is older than the given timestamp. fn get_registry_items_to_clean_age( conn: &Connection, diff --git a/src/cargo/core/package.rs b/src/cargo/core/package.rs index 37332df87fc..3d7c84a4266 100644 --- a/src/cargo/core/package.rs +++ b/src/cargo/core/package.rs @@ -290,7 +290,7 @@ pub struct PackageSet<'gctx> { sources: RefCell>, gctx: &'gctx GlobalContext, multi: Multi, - /// Used to prevent reusing the PackageSet to download twice. + /// Used to prevent reusing the `PackageSet` to download twice. downloading: Cell, /// Whether or not to use curl HTTP/2 multiplexing. multiplexing: bool, diff --git a/src/cargo/core/profiles.rs b/src/cargo/core/profiles.rs index ce2c9e414f6..b7e8fe9c904 100644 --- a/src/cargo/core/profiles.rs +++ b/src/cargo/core/profiles.rs @@ -1003,16 +1003,16 @@ pub struct UnitFor { /// └── shared_dep build.rs /// ``` /// - /// In this example, `foo build.rs` is HOST=true, HOST_FEATURES=false. + /// In this example, `foo build.rs` is `HOST=true`, `HOST_FEATURES=false`. /// This is so that `foo build.rs` gets the profile settings for build - /// scripts (HOST=true) and features of foo (HOST_FEATURES=false) because + /// scripts (`HOST=true`) and features of foo (`HOST_FEATURES=false`) because /// build scripts need to know which features their package is being built /// with. /// /// But in the case of `shared_dep`, when built as a build dependency, /// both flags are true (it only wants the build-dependency features). /// When `shared_dep` is built as a normal dependency, then `shared_dep - /// build.rs` is HOST=true, HOST_FEATURES=false for the same reasons that + /// build.rs` is `HOST=true`, `HOST_FEATURES=false` for the same reasons that /// foo's build script is set that way. host_features: bool, /// How Cargo processes the `panic` setting or profiles. @@ -1139,7 +1139,7 @@ impl UnitFor { /// Returns a new copy updated based on the target dependency. /// - /// This is where the magic happens that the host/host_features settings + /// This is where the magic happens that the `host`/`host_features` settings /// transition in a sticky fashion. As the dependency graph is being /// built, once those flags are set, they stay set for the duration of /// that portion of tree. diff --git a/src/cargo/core/resolver/features.rs b/src/cargo/core/resolver/features.rs index 29d90957ae5..5b05b23f841 100644 --- a/src/cargo/core/resolver/features.rs +++ b/src/cargo/core/resolver/features.rs @@ -210,7 +210,7 @@ impl FeatureOpts { Ok(opts) } - /// Creates a new FeatureOpts for the given behavior. + /// Creates a new `FeatureOpts` for the given behavior. pub fn new_behavior(behavior: ResolveBehavior, has_dev_units: HasDevUnits) -> FeatureOpts { match behavior { ResolveBehavior::V1 => FeatureOpts::default(), @@ -259,7 +259,7 @@ pub struct CliFeatures { } impl CliFeatures { - /// Creates a new CliFeatures from the given command-line flags. + /// Creates a new `CliFeatures` from the given command-line flags. pub fn from_command_line( features: &[String], all_features: bool, @@ -291,7 +291,7 @@ impl CliFeatures { }) } - /// Creates a new CliFeatures with the given `all_features` setting. + /// Creates a new `CliFeatures` with the given `all_features` setting. pub fn new_all(all_features: bool) -> CliFeatures { CliFeatures { features: Rc::new(BTreeSet::new()), @@ -330,7 +330,7 @@ impl ResolvedFeatures { } /// Variant of `activated_features` that returns `None` if this is - /// not a valid pkg_id/is_build combination. Used in places which do + /// not a valid `pkg_id/is_build` combination. Used in places which do /// not know which packages are activated (like `cargo clean`). pub fn activated_features_unverified( &self, @@ -559,7 +559,7 @@ impl<'a, 'gctx> FeatureResolver<'a, 'gctx> { Ok(()) } - /// Activate a single FeatureValue for a package. + /// Activate a single `FeatureValue` for a package. fn activate_fv( &mut self, pkg_id: PackageId, @@ -734,7 +734,7 @@ impl<'a, 'gctx> FeatureResolver<'a, 'gctx> { Ok(()) } - /// Returns Vec of FeatureValues from a Dependency definition. + /// Returns Vec of `FeatureValues` from a Dependency definition. fn fvs_from_dependency(&self, dep_id: PackageId, dep: &Dependency) -> Vec { let summary = self.resolve.summary(dep_id); let feature_map = summary.features(); @@ -749,7 +749,7 @@ impl<'a, 'gctx> FeatureResolver<'a, 'gctx> { result } - /// Returns Vec of FeatureValues from a set of command-line features. + /// Returns Vec of `FeatureValues` from a set of command-line features. fn fvs_from_requested( &self, pkg_id: PackageId, diff --git a/src/cargo/core/resolver/resolve.rs b/src/cargo/core/resolver/resolve.rs index ca3ee43a2ba..2b532c6548d 100644 --- a/src/cargo/core/resolver/resolve.rs +++ b/src/cargo/core/resolver/resolve.rs @@ -86,7 +86,7 @@ pub enum ResolveVersion { /// * Introduced in 2020 in version 1.47. /// * New lockfiles use V3 by default from in 1.53 to 1.82. V3, - /// SourceId URL serialization is aware of URL encoding. For example, + /// `SourceId` URL serialization is aware of URL encoding. For example, /// `?branch=foo bar` is now encoded as `?branch=foo+bar` and can be decoded /// back and forth correctly. /// diff --git a/src/cargo/core/resolver/types.rs b/src/cargo/core/resolver/types.rs index a3f391a897b..2dc5d44ca33 100644 --- a/src/cargo/core/resolver/types.rs +++ b/src/cargo/core/resolver/types.rs @@ -150,7 +150,7 @@ pub struct ResolveOpts { } impl ResolveOpts { - /// Creates a ResolveOpts that resolves everything. + /// Creates a `ResolveOpts` that resolves everything. pub fn everything() -> ResolveOpts { ResolveOpts { dev_deps: true, @@ -227,7 +227,7 @@ pub struct RemainingDeps { time: u32, /// the data is augmented by the insertion time. /// This insures that no two items will cmp eq. - /// Forcing the OrdSet into a multi set. + /// Forcing the `OrdSet` into a multi set. data: im_rc::OrdSet<(DepsFrame, u32)>, } diff --git a/src/cargo/core/source_id.rs b/src/cargo/core/source_id.rs index 53eb7f16f7e..663f69b5751 100644 --- a/src/cargo/core/source_id.rs +++ b/src/cargo/core/source_id.rs @@ -209,7 +209,7 @@ impl SourceId { SourceId::new(SourceKind::Git(reference), url.clone(), None) } - /// Creates a SourceId from a remote registry URL when the registry name + /// Creates a `SourceId` from a remote registry URL when the registry name /// cannot be determined, e.g. a user passes `--index` directly from CLI. /// /// Use [`SourceId::for_alt_registry`] if a name can provided, which @@ -446,7 +446,7 @@ impl SourceId { } /// Check if the precise data field stores information for this `name` - /// from a call to [SourceId::with_precise_registry_version]. + /// from a call to [`SourceId::with_precise_registry_version`]. /// /// If so return the version currently in the lock file and the version to be updated to. pub fn precise_registry_version( @@ -502,7 +502,7 @@ impl SourceId { /// On a registry dependency we also need to keep track of the package that /// should be updated and even which of the versions should be updated. /// All of this gets encoded in the precise field using this method. - /// The data can be read with [SourceId::precise_registry_version] + /// The data can be read with [`SourceId::precise_registry_version`] pub fn with_precise_registry_version( self, name: InternedString, @@ -665,7 +665,7 @@ impl fmt::Display for SourceId { } } -/// The hash of SourceId is used in the name of some Cargo folders, so shouldn't +/// The hash of `SourceId` is used in the name of some Cargo folders, so shouldn't /// vary. `as_str` gives the serialisation of a url (which has a spec) and so /// insulates against possible changes in how the url crate does hashing. impl Hash for SourceId { diff --git a/src/cargo/core/summary.rs b/src/cargo/core/summary.rs index 1b07bcb9b4c..168a20fc6b2 100644 --- a/src/cargo/core/summary.rs +++ b/src/cargo/core/summary.rs @@ -185,7 +185,7 @@ const _: fn() = || { }; /// Checks features for errors, bailing out a CargoResult:Err if invalid, -/// and creates FeatureValues for each feature. +/// and creates `FeatureValues` for each feature. fn build_feature_map( features: &BTreeMap>, dependencies: &[Dependency], @@ -351,7 +351,7 @@ fn build_feature_map( Ok(map) } -/// FeatureValue represents the types of dependencies a feature can have. +/// `FeatureValue` represents the types of dependencies a feature can have. #[derive(Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)] pub enum FeatureValue { /// A feature enabling another feature. diff --git a/src/cargo/core/workspace.rs b/src/cargo/core/workspace.rs index b2f78df61c1..a2345cf676b 100644 --- a/src/cargo/core/workspace.rs +++ b/src/cargo/core/workspace.rs @@ -396,7 +396,7 @@ impl<'gctx> Workspace<'gctx> { .unwrap_or(&self.current_manifest) } - /// Returns the root Package or VirtualManifest. + /// Returns the root Package or `VirtualManifest`. pub fn root_maybe(&self) -> &MaybePackage { self.packages.get(self.root_manifest()) } diff --git a/src/cargo/ops/cargo_add/mod.rs b/src/cargo/ops/cargo_add/mod.rs index 9e8e5d1b870..85497718168 100644 --- a/src/cargo/ops/cargo_add/mod.rs +++ b/src/cargo/ops/cargo_add/mod.rs @@ -265,7 +265,7 @@ pub fn add(workspace: &Workspace<'_>, options: &AddOptions<'_>) -> CargoResult<( pub struct DepOp { /// Describes the crate pub crate_spec: Option, - /// Dependency key, overriding the package name in crate_spec + /// Dependency key, overriding the package name in `crate_spec` pub rename: Option, /// Feature flags to activate diff --git a/src/cargo/ops/cargo_compile/mod.rs b/src/cargo/ops/cargo_compile/mod.rs index ae3511ef04d..d03e529be74 100644 --- a/src/cargo/ops/cargo_compile/mod.rs +++ b/src/cargo/ops/cargo_compile/mod.rs @@ -747,7 +747,7 @@ fn traverse_and_share( new_unit } -/// Removes duplicate CompileMode::Doc units that would cause problems with +/// Removes duplicate `CompileMode::Doc` units that would cause problems with /// filename collisions. /// /// Rustdoc only separates units by crate name in the file directory diff --git a/src/cargo/ops/cargo_new.rs b/src/cargo/ops/cargo_new.rs index 9de0f58dc70..88d2d6bf162 100644 --- a/src/cargo/ops/cargo_new.rs +++ b/src/cargo/ops/cargo_new.rs @@ -572,7 +572,7 @@ pub fn init(opts: &NewOptions, gctx: &GlobalContext) -> CargoResult, @@ -613,7 +613,7 @@ impl IgnoreList { ignore_items.join("\n") + "\n" } - /// format_existing is used to format the IgnoreList when the ignore file + /// `format_existing` is used to format the `IgnoreList` when the ignore file /// already exists. It reads the contents of the given `BufRead` and /// checks if the contents of the ignore list are already existing in the /// file. diff --git a/src/cargo/ops/cargo_update.rs b/src/cargo/ops/cargo_update.rs index 0c9b885da70..4fb7c30509e 100644 --- a/src/cargo/ops/cargo_update.rs +++ b/src/cargo/ops/cargo_update.rs @@ -380,7 +380,7 @@ fn upgrade_dependency( /// cargo-edit. Returns true if any file has changed. /// /// Some of the checks here are duplicating checks already done in -/// upgrade_manifests/upgrade_dependency. Why? Let's say upgrade_dependency has +/// `upgrade_manifests/upgrade_dependency`. Why? Let's say `upgrade_dependency` has /// found that dependency foo was eligible for an upgrade. But foo can occur in /// multiple manifest files, and even multiple times in the same manifest file, /// and may be pinned, renamed, etc. in some of the instances. So we still need diff --git a/src/cargo/ops/common_for_install_and_uninstall.rs b/src/cargo/ops/common_for_install_and_uninstall.rs index f26d1b117b7..996922baf90 100644 --- a/src/cargo/ops/common_for_install_and_uninstall.rs +++ b/src/cargo/ops/common_for_install_and_uninstall.rs @@ -98,7 +98,7 @@ pub struct CrateListingV1 { } impl InstallTracker { - /// Create an InstallTracker from information on disk. + /// Create an `InstallTracker` from information on disk. pub fn load(gctx: &GlobalContext, root: &Filesystem) -> CargoResult { let v1_lock = root.open_rw_exclusive_create(Path::new(".crates.toml"), gctx, "crate metadata")?; @@ -153,7 +153,7 @@ impl InstallTracker { /// Returns a tuple `(freshness, map)`. `freshness` indicates if the /// package should be built (`Dirty`) or if it is already up-to-date /// (`Fresh`) and should be skipped. The map maps binary names to the - /// PackageId that installed it (which is None if not known). + /// `PackageId` that installed it (which is `None` if not known). /// /// If there are no duplicates, then it will be considered `Dirty` (i.e., /// it is OK to build/install). @@ -250,7 +250,7 @@ impl InstallTracker { /// Check if any executables are already installed. /// /// Returns a map of duplicates, the key is the executable name and the - /// value is the PackageId that is already installed. The PackageId is + /// value is the `PackageId` that is already installed. The `PackageId` is /// None if it is an untracked executable. fn find_duplicates( &self, @@ -762,7 +762,7 @@ where } } -/// Helper to convert features to a BTreeSet. +/// Helper to convert features to a `BTreeSet`. fn feature_set(features: &Rc>) -> BTreeSet { features.iter().map(|s| s.to_string()).collect() } diff --git a/src/cargo/ops/registry/mod.rs b/src/cargo/ops/registry/mod.rs index ea49a5dfa3b..0189b2b2d2c 100644 --- a/src/cargo/ops/registry/mod.rs +++ b/src/cargo/ops/registry/mod.rs @@ -176,7 +176,7 @@ fn registry<'gctx>( )) } -/// Gets the SourceId for an index or registry setting. +/// Gets the `SourceId` for an index or registry setting. /// /// The `index` and `reg` values are from the command-line or config settings. /// If both are None, and no source-replacement is configured, returns the source for crates.io. @@ -314,7 +314,7 @@ pub(crate) struct RegistrySourceIds { /// Use when interacting with the source (querying / publishing , etc) /// /// The source for crates.io may be replaced by a built-in source for accessing crates.io with - /// the sparse protocol, or a source for the testing framework (when the replace_crates_io + /// the sparse protocol, or a source for the testing framework (when the `replace_crates_io` /// function is used) /// /// User-defined source replacement is not applied. diff --git a/src/cargo/ops/tree/graph.rs b/src/cargo/ops/tree/graph.rs index 25939df8e18..1b9a3bc104a 100644 --- a/src/cargo/ops/tree/graph.rs +++ b/src/cargo/ops/tree/graph.rs @@ -74,9 +74,9 @@ pub struct Graph<'a> { /// For example `--features foo` will mark the "foo" node here. cli_features: HashSet, /// Map of dependency names, used for building internal feature map for - /// dep_name/feat_name syntax. + /// `dep_name/feat_name` syntax. /// - /// Key is the index of a package node, value is a map of dep_name to a + /// Key is the index of a package node, value is a map of `dep_name` to a /// set of `(pkg_node_index, is_optional)`. dep_name_map: HashMap>>, } @@ -126,7 +126,7 @@ impl<'a> Graph<'a> { &self.nodes[index] } - /// Given a slice of PackageIds, returns the indexes of all nodes that match. + /// Given a slice of `PackageIds`, returns the indexes of all nodes that match. pub fn indexes_from_ids(&self, package_ids: &[PackageId]) -> Vec { let mut result: Vec<(&Node, usize)> = self .nodes diff --git a/src/cargo/sources/git/known_hosts.rs b/src/cargo/sources/git/known_hosts.rs index 25bcf478bd1..b832886bc37 100644 --- a/src/cargo/sources/git/known_hosts.rs +++ b/src/cargo/sources/git/known_hosts.rs @@ -7,9 +7,9 @@ //! messages, guiding them to understand the issue and how to resolve it. //! //! Note that there are a lot of limitations here. This reads OpenSSH -//! known_hosts files from well-known locations, but it does not read OpenSSH +//! `known_hosts` files from well-known locations, but it does not read OpenSSH //! config files. The config file can change the behavior of how OpenSSH -//! handles known_hosts files. For example, some things we don't handle: +//! handles `known_hosts` files. For example, some things we don't handle: //! //! - `GlobalKnownHostsFile` — Changes the location of the global host file. //! - `UserKnownHostsFile` — Changes the location of the user's host file. @@ -516,7 +516,7 @@ fn known_host_files(gctx: &GlobalContext) -> Vec { result } -/// The location of the user's known_hosts file. +/// The location of the user's `known_hosts` file. fn user_known_host_location() -> Option { // NOTE: This is a potentially inaccurate prediction of what the user // actually wants. The actual location depends on several factors: @@ -619,7 +619,7 @@ fn hashed_hostname_matches(host: &str, hashed: &str) -> bool { hashed_host == &result[..] } -/// Loads an OpenSSH known_hosts file. +/// Loads an OpenSSH `known_hosts` file. fn load_hostfile(path: &Path) -> Result, anyhow::Error> { let contents = cargo_util::paths::read(path)?; Ok(load_hostfile_contents(path, &contents)) diff --git a/src/cargo/sources/git/source.rs b/src/cargo/sources/git/source.rs index 7a6cc7851a1..1c1dc4cd720 100644 --- a/src/cargo/sources/git/source.rs +++ b/src/cargo/sources/git/source.rs @@ -1,4 +1,4 @@ -//! See [GitSource]. +//! See [`GitSource`]. use crate::core::global_cache_tracker; use crate::core::GitReference; diff --git a/src/cargo/sources/registry/index/mod.rs b/src/cargo/sources/registry/index/mod.rs index 66afa52ab08..6c6d6f3e6fd 100644 --- a/src/cargo/sources/registry/index/mod.rs +++ b/src/cargo/sources/registry/index/mod.rs @@ -531,7 +531,7 @@ impl Summaries { /// /// * `root` --- this is the root argument passed to `load` /// * `name` --- the name of the package. - /// * `source_id` --- the registry's SourceId used when parsing JSON blobs + /// * `source_id` --- the registry's `SourceId` used when parsing JSON blobs /// to create summaries. /// * `load` --- the actual index implementation which may be very slow to /// call. We avoid this if we can. diff --git a/src/cargo/sources/registry/mod.rs b/src/cargo/sources/registry/mod.rs index 4cfe2005b46..4a4c22b468e 100644 --- a/src/cargo/sources/registry/mod.rs +++ b/src/cargo/sources/registry/mod.rs @@ -422,7 +422,7 @@ pub trait RegistryData { /// Returns the [`Path`] to the [`Filesystem`]. fn assert_index_locked<'a>(&self, path: &'a Filesystem) -> &'a Path; - /// Block until all outstanding Poll::Pending requests are Poll::Ready. + /// Block until all outstanding `Poll::Pending` requests are `Poll::Ready`. fn block_until_ready(&mut self) -> CargoResult<()>; } diff --git a/src/cargo/util/auth/mod.rs b/src/cargo/util/auth/mod.rs index cf4cccb9753..2576b4baba1 100644 --- a/src/cargo/util/auth/mod.rs +++ b/src/cargo/util/auth/mod.rs @@ -573,7 +573,7 @@ fn credential_action( /// Returns the token to use for the given registry. /// If a `login_url` is provided and a token is not available, the -/// login_url will be included in the returned error. +/// `login_url` will be included in the returned error. pub fn auth_token( gctx: &GlobalContext, sid: &SourceId, diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs index 16e588cd480..e11a902a635 100644 --- a/src/cargo/util/command_prelude.rs +++ b/src/cargo/util/command_prelude.rs @@ -62,7 +62,7 @@ pub trait CommandExt: Sized { ) } - /// Variant of arg_package_spec that does not include the `--all` flag + /// Variant of `arg_package_spec` that does not include the `--all` flag /// (but does include `--workspace`). Used to avoid confusion with /// historical uses of `--all`. fn arg_package_spec_no_all( diff --git a/src/cargo/util/context/de.rs b/src/cargo/util/context/de.rs index d35325a50cf..9a91583ed15 100644 --- a/src/cargo/util/context/de.rs +++ b/src/cargo/util/context/de.rs @@ -16,9 +16,9 @@ pub(super) struct Deserializer<'gctx> { pub(super) key: ConfigKey, /// Whether or not this key part is allowed to be an inner table. For /// example, `profile.dev.build-override` needs to check if - /// CARGO_PROFILE_DEV_BUILD_OVERRIDE_ prefixes exist. But - /// CARGO_BUILD_TARGET should not check for prefixes because it would - /// collide with CARGO_BUILD_TARGET_DIR. See `ConfigMapAccess` for + /// `CARGO_PROFILE_DEV_BUILD_OVERRIDE_` prefixes exist. But + /// `CARGO_BUILD_TARGET` should not check for prefixes because it would + /// collide with `CARGO_BUILD_TARGET_DIR`. See `ConfigMapAccess` for /// details. pub(super) env_prefix_ok: bool, } diff --git a/src/cargo/util/context/mod.rs b/src/cargo/util/context/mod.rs index b9589aa6542..54a2f2d2a1f 100644 --- a/src/cargo/util/context/mod.rs +++ b/src/cargo/util/context/mod.rs @@ -116,7 +116,7 @@ use super::auth::RegistryConfig; // Helper macro for creating typed access methods. macro_rules! get_value_typed { ($name:ident, $ty:ty, $variant:ident, $expected:expr) => { - /// Low-level private method for getting a config value as an OptValue. + /// Low-level private method for getting a config value as an [`OptValue`]. fn $name(&self, key: &ConfigKey) -> Result, ConfigError> { let cv = self.get_cv(key)?; let env = self.get_config_env::<$ty>(key)?; @@ -244,7 +244,7 @@ pub struct GlobalContext { /// NOTE: this should be set before `configure()`. If calling this from an integration test, /// consider using `ConfigBuilder::enable_nightly_features` instead. pub nightly_features_allowed: bool, - /// WorkspaceRootConfigs that have been found + /// `WorkspaceRootConfigs` that have been found pub ws_roots: RefCell>, /// The global cache tracker is a database used to track disk cache usage. global_cache_tracker: LazyCell>, @@ -909,7 +909,7 @@ impl GlobalContext { } } - /// Helper for StringList type to get something that is a string or list. + /// Helper for `StringList` type to get something that is a string or list. fn get_list_or_string( &self, key: &ConfigKey, @@ -1888,7 +1888,7 @@ impl GlobalContext { Ok(()) } - /// Returns a list of [target.'cfg()'] tables. + /// Returns a list of [target.'`cfg()`'] tables. /// /// The list is sorted by the table name. pub fn target_cfgs(&self) -> CargoResult<&Vec<(String, TargetCfgConfig)>> { @@ -2916,7 +2916,7 @@ impl StringList { } } -/// StringList automatically merges config values with environment values, +/// `StringList` automatically merges config values with environment values, /// this instead follows the precedence rules, so that eg. a string list found /// in the environment will be used instead of one in a config file. /// diff --git a/src/cargo/util/context/path.rs b/src/cargo/util/context/path.rs index 706bc946d95..bf96b5846be 100644 --- a/src/cargo/util/context/path.rs +++ b/src/cargo/util/context/path.rs @@ -82,7 +82,7 @@ impl<'de> serde::Deserialize<'de> for PathAndArgs { } impl PathAndArgs { - /// Construct a PathAndArgs from a string. The string will be split on ascii whitespace, + /// Construct a `PathAndArgs` from a string. The string will be split on ascii whitespace, /// with the first item being treated as a `ConfigRelativePath` to the executable, and subsequent /// items as arguments. pub fn from_whitespace_separated_string(p: &Value) -> PathAndArgs { diff --git a/src/cargo/util/dependency_queue.rs b/src/cargo/util/dependency_queue.rs index 5650f4b251e..d4628bc75f3 100644 --- a/src/cargo/util/dependency_queue.rs +++ b/src/cargo/util/dependency_queue.rs @@ -25,7 +25,7 @@ pub struct DependencyQueue { /// package. /// /// This map is statically known and does not get updated throughout the - /// lifecycle of the DependencyQueue. + /// lifecycle of the `DependencyQueue`. /// /// This is sort of like a `HashMap<(N, E), HashSet>` map, but more /// easily indexable with just an `N` @@ -113,7 +113,7 @@ impl DependencyQueue { /// Creates a flattened reverse dependency list. For a given key, finds the /// set of nodes which depend on it, including transitively. This is different - /// from self.reverse_dep_map because self.reverse_dep_map only maps one level + /// from `self.reverse_dep_map` because `self.reverse_dep_map` only maps one level /// of reverse dependencies. fn depth<'a, N: Hash + Eq + Clone, E: Hash + Eq + Clone>( key: &N, diff --git a/src/cargo/util/rustc.rs b/src/cargo/util/rustc.rs index c9a5ee82109..19aa447edd9 100644 --- a/src/cargo/util/rustc.rs +++ b/src/cargo/util/rustc.rs @@ -26,9 +26,9 @@ pub struct Rustc { pub workspace_wrapper: Option, /// Verbose version information (the output of `rustc -vV`) pub verbose_version: String, - /// The rustc version (`1.23.4-beta.2`), this comes from verbose_version. + /// The rustc version (`1.23.4-beta.2`), this comes from `verbose_version`. pub version: semver::Version, - /// The host triple (arch-platform-OS), this comes from verbose_version. + /// The host triple (arch-platform-OS), this comes from `verbose_version`. pub host: InternedString, /// The rustc full commit hash, this comes from `verbose_version`. pub commit_hash: Option, diff --git a/src/cargo/util/semver_ext.rs b/src/cargo/util/semver_ext.rs index 1029f88aec3..9c19eb30130 100644 --- a/src/cargo/util/semver_ext.rs +++ b/src/cargo/util/semver_ext.rs @@ -130,7 +130,7 @@ impl OptVersionReq { } /// Allows to match pre-release in SemVer-Compatible way. - /// See [`semver_eval_ext`] for matches_prerelease semantics. + /// See [`semver_eval_ext`] for `matches_prerelease` semantics. pub fn matches_prerelease(&self, version: &Version) -> bool { if let OptVersionReq::Req(req) = self { return req.matches_prerelease(version); diff --git a/src/cargo/util/toml_mut/dependency.rs b/src/cargo/util/toml_mut/dependency.rs index 48ebe7ad5d9..836fb738363 100644 --- a/src/cargo/util/toml_mut/dependency.rs +++ b/src/cargo/util/toml_mut/dependency.rs @@ -176,7 +176,7 @@ impl Dependency { self.public } - /// Get the SourceID for this dependency. + /// Get the `SourceID` for this dependency. pub fn source_id(&self, gctx: &GlobalContext) -> CargoResult> { match &self.source.as_ref() { Some(Source::Registry(_)) | None => { @@ -903,7 +903,7 @@ impl PathSource { self } - /// Get the SourceID for this dependency. + /// Get the `SourceID` for this dependency. pub fn source_id(&self) -> CargoResult { SourceId::for_path(&self.path) } @@ -967,7 +967,7 @@ impl GitSource { self } - /// Get the SourceID for this dependency. + /// Get the `SourceID` for this dependency. pub fn source_id(&self) -> CargoResult { let git_url = self.git.parse::()?; let git_ref = self.git_ref(); diff --git a/tests/testsuite/cfg.rs b/tests/testsuite/cfg.rs index 0b71e861b58..7e90b51a626 100644 --- a/tests/testsuite/cfg.rs +++ b/tests/testsuite/cfg.rs @@ -1,4 +1,4 @@ -//! Tests for cfg() expressions. +//! Tests for `cfg()` expressions. use cargo_test_support::prelude::*; use cargo_test_support::registry::Package; diff --git a/tests/testsuite/collisions.rs b/tests/testsuite/collisions.rs index f42e8f68787..1f69f3e7f44 100644 --- a/tests/testsuite/collisions.rs +++ b/tests/testsuite/collisions.rs @@ -1,5 +1,5 @@ //! Tests for when multiple artifacts have the same output filename. -//! See https://github.com/rust-lang/cargo/issues/6313 for more details. +//! See for more details. //! Ideally these should never happen, but I don't think we'll ever be able to //! prevent all collisions. diff --git a/tests/testsuite/fix_n_times.rs b/tests/testsuite/fix_n_times.rs index e6092ae8c55..179602ff01a 100644 --- a/tests/testsuite/fix_n_times.rs +++ b/tests/testsuite/fix_n_times.rs @@ -3,7 +3,7 @@ //! //! These tests use a replacement of rustc ("rustc-fix-shim") which emits JSON //! messages based on what the test is exercising. It uses an environment -//! variable RUSTC_FIX_SHIM_SEQUENCE which determines how it should behave +//! variable `RUSTC_FIX_SHIM_SEQUENCE` which determines how it should behave //! based on how many times `rustc` has run. It keeps track of how many times //! rustc has run in a local file. //! diff --git a/tests/testsuite/global_cache_tracker.rs b/tests/testsuite/global_cache_tracker.rs index 8e812fc7256..dfd698f5f8b 100644 --- a/tests/testsuite/global_cache_tracker.rs +++ b/tests/testsuite/global_cache_tracker.rs @@ -93,7 +93,7 @@ fn now() -> SystemTime { } /// Helper for simulating running cargo in the past. Use with the -/// __CARGO_TEST_LAST_USE_NOW environment variable. +/// `__CARGO_TEST_LAST_USE_NOW` environment variable. fn days_ago_unix(n: u64) -> String { days_ago(n) .duration_since(SystemTime::UNIX_EPOCH) @@ -103,7 +103,7 @@ fn days_ago_unix(n: u64) -> String { } /// Helper for simulating running cargo in the past. Use with the -/// __CARGO_TEST_LAST_USE_NOW environment variable. +/// `__CARGO_TEST_LAST_USE_NOW` environment variable. fn months_ago_unix(n: u64) -> String { days_ago_unix(n * 30) } diff --git a/tests/testsuite/https.rs b/tests/testsuite/https.rs index f99b61beca3..1f347e90239 100644 --- a/tests/testsuite/https.rs +++ b/tests/testsuite/https.rs @@ -1,7 +1,7 @@ //! Network tests for https transport. //! -//! Note that these tests will generally require setting CARGO_CONTAINER_TESTS -//! or CARGO_PUBLIC_NETWORK_TESTS. +//! Note that these tests will generally require setting `CARGO_CONTAINER_TESTS` +//! or `CARGO_PUBLIC_NETWORK_TESTS`. use cargo_test_support::containers::Container; use cargo_test_support::prelude::*; diff --git a/tests/testsuite/ssh.rs b/tests/testsuite/ssh.rs index 2cf6a57f691..ac2b9596c01 100644 --- a/tests/testsuite/ssh.rs +++ b/tests/testsuite/ssh.rs @@ -1,7 +1,7 @@ //! Network tests for SSH connections. //! -//! Note that these tests will generally require setting CARGO_CONTAINER_TESTS -//! or CARGO_PUBLIC_NETWORK_TESTS. +//! Note that these tests will generally require setting `CARGO_CONTAINER_TESTS` +//! or `CARGO_PUBLIC_NETWORK_TESTS`. //! //! NOTE: The container tests almost certainly won't work on Windows. From e3065568d0f68e254cacfe1c09caabfe51d2cbe0 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 15 Nov 2024 08:57:17 -0600 Subject: [PATCH 4/4] docs: Focus the summary for API items This was aided by `clippy::too_long_first_doc_paragraph` --- crates/cargo-test-support/src/lib.rs | 3 ++- crates/home/src/env.rs | 16 ++++++++++++---- crates/resolver-tests/src/sat.rs | 11 +++++++---- credential/cargo-credential/src/lib.rs | 4 +++- src/cargo/core/compiler/build_config.rs | 1 + src/cargo/util/context/mod.rs | 10 +++++----- src/cargo/util/workspace.rs | 2 ++ 7 files changed, 32 insertions(+), 15 deletions(-) diff --git a/crates/cargo-test-support/src/lib.rs b/crates/cargo-test-support/src/lib.rs index fcbbed26562..7812835f694 100644 --- a/crates/cargo-test-support/src/lib.rs +++ b/crates/cargo-test-support/src/lib.rs @@ -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 = OnceLock::new(); let slow_cpu_multiplier = SLOW_CPU_MULTIPLIER.get_or_init(|| { diff --git a/crates/home/src/env.rs b/crates/home/src/env.rs index 13bc17c6eb8..f5a6a2231a8 100644 --- a/crates/home/src/env.rs +++ b/crates/home/src/env.rs @@ -47,7 +47,9 @@ pub fn home_dir_with_env(env: &dyn Env) -> Option { 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. @@ -57,7 +59,9 @@ pub fn cargo_home_with_env(env: &dyn Env) -> io::Result { } /// Variant of `cargo_home_with_cwd` where the environment source is -/// parameterized. This is specifically to support in-process testing scenarios +/// 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. pub fn cargo_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result { @@ -77,7 +81,9 @@ pub fn cargo_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result } /// Variant of `cargo_home_with_cwd` where the environment source is -/// parameterized. This is specifically to support in-process testing scenarios +/// 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. pub fn rustup_home_with_env(env: &dyn Env) -> io::Result { @@ -86,7 +92,9 @@ pub fn rustup_home_with_env(env: &dyn Env) -> io::Result { } /// Variant of `cargo_home_with_cwd` where the environment source is -/// parameterized. This is specifically to support in-process testing scenarios +/// 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. pub fn rustup_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result { diff --git a/crates/resolver-tests/src/sat.rs b/crates/resolver-tests/src/sat.rs index 93370a8c405..d67a1c24981 100644 --- a/crates/resolver-tests/src/sat.rs +++ b/crates/resolver-tests/src/sat.rs @@ -20,9 +20,10 @@ fn log_bits(x: usize) -> usize { (num_bits::() 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. /// diff --git a/credential/cargo-credential/src/lib.rs b/credential/cargo-credential/src/lib.rs index c8e64b983af..ce99e036e1f 100644 --- a/credential/cargo-credential/src/lib.rs +++ b/credential/cargo-credential/src/lib.rs @@ -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, diff --git a/src/cargo/core/compiler/build_config.rs b/src/cargo/core/compiler/build_config.rs index ad881bb318d..80aa592dde3 100644 --- a/src/cargo/core/compiler/build_config.rs +++ b/src/cargo/core/compiler/build_config.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 diff --git a/src/cargo/util/context/mod.rs b/src/cargo/util/context/mod.rs index 54a2f2d2a1f..9824eff9017 100644 --- a/src/cargo/util/context/mod.rs +++ b/src/cargo/util/context/mod.rs @@ -113,7 +113,7 @@ use environment::Env; use super::auth::RegistryConfig; -// Helper macro for creating typed access methods. +/// Helper macro for creating typed access methods. macro_rules! get_value_typed { ($name:ident, $ty:ty, $variant:ident, $expected:expr) => { /// Low-level private method for getting a config value as an [`OptValue`]. @@ -2916,11 +2916,11 @@ impl StringList { } } -/// `StringList` automatically merges config values with environment values, -/// this instead follows the precedence rules, so that eg. a string list found -/// in the environment will be used instead of one in a config file. +/// Alternative to [`StringList`] that follows precedence rules, rather than merging config values with environment values, /// -/// This is currently only used by `PathAndArgs` +/// e.g. a string list found in the environment will be used instead of one in a config file. +/// +/// This is currently only used by [`PathAndArgs`] #[derive(Debug, Deserialize)] pub struct UnmergedStringList(Vec); diff --git a/src/cargo/util/workspace.rs b/src/cargo/util/workspace.rs index 754775596fa..9039cae8439 100644 --- a/src/cargo/util/workspace.rs +++ b/src/cargo/util/workspace.rs @@ -95,6 +95,8 @@ pub fn print_available_tests(ws: &Workspace<'_>, options: &CompileOptions) -> Ca print_available_targets(Target::is_test, ws, options, "--test", "test targets") } +/// The source path and its current dir for use in compilation. +/// /// The path that we pass to rustc is actually fairly important because it will /// show up in error messages (important for readability), debug information /// (important for caching), etc. As a result we need to be pretty careful how we