From 92c9d70dd2ad267823ad14e147c757f04b4bb9b8 Mon Sep 17 00:00:00 2001
From: Weihang Lo <me@weihanglo.tw>
Date: Sat, 3 Jun 2023 22:23:31 +0100
Subject: [PATCH] doc: the first line should be a simple sentence instead of a
 heading

This is a writing style enforced in The Rust Standard Library.
---
 src/cargo/core/compiler/fingerprint/mod.rs   | 5 ++++-
 src/cargo/core/compiler/unit_dependencies.rs | 2 +-
 src/cargo/core/profiles.rs                   | 2 +-
 src/cargo/core/resolver/features.rs          | 3 ++-
 src/cargo/ops/cargo_compile/mod.rs           | 6 ++----
 src/cargo/util/profile.rs                    | 2 +-
 6 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/src/cargo/core/compiler/fingerprint/mod.rs b/src/cargo/core/compiler/fingerprint/mod.rs
index a3523110bba..aa8be50f758 100644
--- a/src/cargo/core/compiler/fingerprint/mod.rs
+++ b/src/cargo/core/compiler/fingerprint/mod.rs
@@ -1,8 +1,11 @@
-//! # Fingerprints
+//! Tracks changes to determine if something needs to be recompiled.
 //!
 //! This module implements change-tracking so that Cargo can know whether or
 //! not something needs to be recompiled. A Cargo [`Unit`] can be either "dirty"
 //! (needs to be recompiled) or "fresh" (it does not need to be recompiled).
+//!
+//! ## Mechanisms affecting freshness
+//!
 //! There are several mechanisms that influence a Unit's freshness:
 //!
 //! - The [`Fingerprint`] is a hash, saved to the filesystem in the
diff --git a/src/cargo/core/compiler/unit_dependencies.rs b/src/cargo/core/compiler/unit_dependencies.rs
index 3bf8b0c77a1..369fd83180d 100644
--- a/src/cargo/core/compiler/unit_dependencies.rs
+++ b/src/cargo/core/compiler/unit_dependencies.rs
@@ -1,4 +1,4 @@
-//! # Constructs the dependency graph for compilation
+//! Constructs the dependency graph for compilation.
 //!
 //! Rust code is typically organized as a set of Cargo packages. The
 //! dependencies between the packages themselves are stored in the
diff --git a/src/cargo/core/profiles.rs b/src/cargo/core/profiles.rs
index b3b6dd9d2c6..5c7d3e2488e 100644
--- a/src/cargo/core/profiles.rs
+++ b/src/cargo/core/profiles.rs
@@ -1,4 +1,4 @@
-//! # Profiles: built-in and customizable compiler flag presets
+//! Handles built-in and customizable compiler flag presets.
 //!
 //! [`Profiles`] is a collections of built-in profiles, and profiles defined
 //! in the root manifest and configurations.
diff --git a/src/cargo/core/resolver/features.rs b/src/cargo/core/resolver/features.rs
index 6b79722caed..3670e87112f 100644
--- a/src/cargo/core/resolver/features.rs
+++ b/src/cargo/core/resolver/features.rs
@@ -1,4 +1,4 @@
-//! # Feature resolver
+//! Resolves conditional compilation for [`features` section] in the manifest.
 //!
 //! This is a [new feature resolver] that runs independently of the main
 //! dependency resolver. It has several options which can enable new feature
@@ -34,6 +34,7 @@
 //!
 //! There are probably other assumptions that I am forgetting.
 //!
+//! [`features` section]: https://doc.rust-lang.org/nightly/cargo/reference/features.html
 //! [new feature resolver]: https://doc.rust-lang.org/nightly/cargo/reference/resolver.html#feature-resolver-version-2
 //! [`resolve_ws_with_opts`]: crate::ops::resolve_ws_with_opts
 
diff --git a/src/cargo/ops/cargo_compile/mod.rs b/src/cargo/ops/cargo_compile/mod.rs
index 3b6043d4fdb..f53a9e93426 100644
--- a/src/cargo/ops/cargo_compile/mod.rs
+++ b/src/cargo/ops/cargo_compile/mod.rs
@@ -1,7 +1,5 @@
-//! # The Cargo "compile" operation
-//!
-//! This module contains the entry point for starting the compilation process
-//! for commands like `build`, `test`, `doc`, `rustc`, etc.
+//! The entry point for starting the compilation process for commands like
+//! `build`, `test`, `doc`, `rustc`, etc.
 //!
 //! The [`compile`] function will do all the work to compile a workspace. A
 //! rough outline is:
diff --git a/src/cargo/util/profile.rs b/src/cargo/util/profile.rs
index 79b544d98c8..29b110492bf 100644
--- a/src/cargo/util/profile.rs
+++ b/src/cargo/util/profile.rs
@@ -1,4 +1,4 @@
-//! # An internal profiler for Cargo itself
+//! An internal performance profiler for Cargo itself.
 //!
 //! > **Note**: This might not be the module you are looking for.
 //! > For information about how Cargo handles compiler flags with profiles,