From f51b9502e2f4cd84723f3892ba60e11b2f6748f1 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 15 Nov 2024 08:57:17 -0600 Subject: [PATCH] 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 fcbbed265626..7812835f6948 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 13bc17c6eb87..f5a6a2231a82 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 93370a8c405e..d67a1c249815 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 c8e64b983af7..ce99e036e1f2 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 ad881bb318d0..80aa592dde3b 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 54a2f2d2a1f9..9824eff90178 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 754775596fac..9039cae84394 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