docs: Focus the summary for API items

This was aided by `clippy::too_long_first_doc_paragraph`

Author: epage

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<u64> = OnceLock::new();
     let slow_cpu_multiplier = SLOW_CPU_MULTIPLIER.get_or_init(|| {

crates/home/src/env.rs

@@ -47,7 +47,9 @@ pub fn home_dir_with_env(env: &dyn Env) -> Option<PathBuf> {
     env.home_dir()
 }
 
-/// Variant of `cargo_home` where the environment source is parameterized. This is
+/// Variant of `cargo_home` where the environment source is parameterized.
+///
+/// This is
 /// specifically to support in-process testing scenarios as environment
 /// variables and user home metadata are normally process global state. See the
 /// [`Env`] trait.
@@ -57,7 +59,9 @@ pub fn cargo_home_with_env(env: &dyn Env) -> io::Result<PathBuf> {
 }
 
 /// 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<PathBuf> {
@@ -77,7 +81,9 @@ pub fn cargo_home_with_cwd_env(env: &dyn Env, cwd: &Path) -> io::Result<PathBuf>
 }
 
 /// Variant of `cargo_home_with_cwd` where the environment source is
-/// parameterized. This is specifically to support in-process testing scenarios
+/// 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<PathBuf> {
@@ -86,7 +92,9 @@ pub fn rustup_home_with_env(env: &dyn Env) -> io::Result<PathBuf> {
 }
 
 /// 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<PathBuf> {

crates/resolver-tests/src/sat.rs

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

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,

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

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

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