docs(lints): Better match clippy in lint section titles

src/cargo/diagnostics/rules/blanket_hint_mostly_unused.rs

@@ -31,7 +31,7 @@ pub static LINT: &Lint = &Lint {
 ### What it does
 Checks if `hint-mostly-unused` being applied to all dependencies.
 
-### Why it is bad
+### Why is this bad?
 `hint-mostly-unused` indicates that most of a crate's API surface will go
 unused by anything depending on it; this hint can speed up the build by
 attempting to minimize compilation time for items that aren't used at all.

src/cargo/diagnostics/rules/implicit_minimum_version_req.rs

@@ -45,7 +45,7 @@ such as `serde = "1"` or `serde = "1.0"`.
 This lint currently only applies to caret requirements
 (the [default requirements](specifying-dependencies.md#default-requirements)).
 
-### Why it is bad
+### Why is this bad?
 
 Version requirements without an explicit full version
 can be misleading about the actual minimum supported version.

src/cargo/diagnostics/rules/missing_lints_inheritance.rs

@@ -29,7 +29,7 @@ pub static LINT: &Lint = &Lint {
 
 Checks for packages without a `lints` table while `workspace.lints` is present.
 
-### Why it is bad
+### Why is this bad?
 
 Many people mistakenly think that `workspace.lints` is implicitly inherited when it is not.
 

src/cargo/diagnostics/rules/mod.rs

@@ -246,6 +246,7 @@ fn find_lint_or_group<'a>(
 #[cfg(test)]
 mod tests {
     use crate::util::data_structures::HashSet;
+    use crate::util::data_structures::IndexMap;
     use itertools::Itertools;
     use snapbox::ToDebug;
     use std::cmp::Reverse;
@@ -267,6 +268,78 @@ mod tests {
         );
     }
 
+    #[test]
+    fn ensure_visible_lint_msrv() {
+        let invalid_msrvs = LINTS
+            .iter()
+            // Only relevant for default lints
+            .filter(|l| !matches!(l.primary_group.default_level, LintLevel::Allow))
+            .filter(|l| l.msrv.map(|v| v < CARGO_LINTS_MSRV).unwrap_or(false))
+            .map(|l| l.name)
+            .join(", ");
+        assert!(
+            invalid_msrvs.is_empty(),
+            "{invalid_msrvs} need `msrv` set so users can use `[lints.cargo]` to disable them"
+        );
+    }
+
+    #[test]
+    fn ensure_docs_sections() {
+        let expected_sections_restriction = &[
+            "### What it does",
+            "### Why restrict this?",
+            "### Drawbacks",
+            "### Example",
+        ];
+        let expected_sections = &[
+            "### What it does",
+            "### Why is this bad?",
+            "### Drawbacks",
+            "### Example",
+        ];
+        for lint in LINTS {
+            dbg!(lint.name);
+            let mut sections = IndexMap::default();
+            let mut title = "";
+            let mut body = Vec::new();
+            let Some(docs) = lint.docs else {
+                continue;
+            };
+            for line in docs.trim().lines() {
+                if line.starts_with("#") {
+                    if !title.is_empty() || !body.is_empty() {
+                        let old = sections.insert(title, body);
+                        assert!(old.is_none(), "duplicate title: `{title:?}`");
+                    }
+                    title = line;
+                    body = Vec::new();
+                } else {
+                    body.push(line);
+                }
+            }
+            if !title.is_empty() || !body.is_empty() {
+                let old = sections.insert(title, body);
+                assert!(old.is_none(), "duplicate title: `{title:?}`");
+            }
+
+            let mut expected = Vec::new();
+            let expected_sections = match lint.primary_group.name {
+                "restriction" => expected_sections_restriction,
+                _ => expected_sections,
+            };
+            for section in expected_sections {
+                let body = match sections.get(section) {
+                    Some(body) => body,
+                    None => continue,
+                };
+                expected.push(*section);
+                expected.extend(body.iter().copied());
+            }
+            let expected = expected.join("\n");
+            snapbox::assert_data_eq!(docs.trim(), expected);
+        }
+    }
+
     #[test]
     fn ensure_sorted_lints() {
         // This will be printed out if the fields are not sorted.

src/cargo/diagnostics/rules/non_kebab_case_bins.rs

@@ -34,7 +34,7 @@ pub static LINT: &Lint = &Lint {
 
 Detect binary names, explicit and implicit, that are not kebab-case
 
-### Why it is bad
+### Why is this bad?
 
 Kebab-case binary names is a common convention among command line tools.
 

src/cargo/diagnostics/rules/non_kebab_case_features.rs

@@ -33,7 +33,7 @@ pub static LINT: &Lint = &Lint {
 
 Detect feature names that are not kebab-case.
 
-### Why it is bad
+### Why restrict this?
 
 Having multiple naming styles within a workspace can be confusing.
 

src/cargo/diagnostics/rules/non_kebab_case_packages.rs

@@ -33,7 +33,7 @@ pub static LINT: &Lint = &Lint {
 
 Detect package names that are not kebab-case.
 
-### Why it is bad
+### Why restrict this?
 
 Having multiple naming styles within a workspace can be confusing.
 

src/cargo/diagnostics/rules/non_snake_case_features.rs

@@ -33,7 +33,7 @@ pub static LINT: &Lint = &Lint {
 
 Detect feature names that are not snake-case.
 
-### Why it is bad
+### Why restrict this?
 
 Having multiple naming styles within a workspace can be confusing.
 

src/cargo/diagnostics/rules/non_snake_case_packages.rs

@@ -33,7 +33,7 @@ pub static LINT: &Lint = &Lint {
 
 Detect package names that are not snake-case.
 
-### Why it is bad
+### Why restrict this?
 
 Having multiple naming styles within a workspace can be confusing.
 

src/cargo/diagnostics/rules/redundant_homepage.rs

@@ -35,7 +35,7 @@ Checks if the value of `package.homepage` is already covered by another field.
 
 See also [`package.homepage` reference documentation](manifest.md#the-homepage-field).
 
-### Why it is bad
+### Why is this bad?
 
 When package browsers render each link, a redundant link adds visual noise.
 

src/cargo/diagnostics/rules/redundant_readme.rs

@@ -37,7 +37,7 @@ Checks for `package.readme` fields that can be inferred.
 
 See also [`package.readme` reference documentation](manifest.md#the-readme-field).
 
-### Why it is bad
+### Why is this bad?
 
 Adds boilerplate.
 

src/cargo/diagnostics/rules/text_direction_codepoint_in_comment.rs

@@ -35,7 +35,7 @@ pub static LINT: &Lint = &Lint {
 Detects Unicode codepoints in manifest comments that change the visual representation of text on screen
 in a way that does not correspond to their on memory representation.
 
-### Why it is bad
+### Why is this bad?
 Unicode allows changing the visual flow of text on screen
 in order to support scripts that are written right-to-left,
 but a specially crafted comment can make code that will be compiled appear to be part of a comment,

src/cargo/diagnostics/rules/text_direction_codepoint_in_literal.rs

@@ -36,7 +36,7 @@ pub static LINT: &Lint = &Lint {
 Detects Unicode codepoints in literals in manifests that change the visual representation of text on screen
 in a way that does not correspond to their on memory representation.
 
-### Why it is bad
+### Why is this bad?
 Unicode allows changing the visual flow of text on screen
 in order to support scripts that are written right-to-left,
 but a specially crafted literal can make code that will be compiled appear to be part of a literal,

src/cargo/diagnostics/rules/unknown_lints.rs

@@ -34,7 +34,7 @@ pub static LINT: &Lint = &Lint {
 ### What it does
 Checks for unknown lints in the `[lints.cargo]` table
 
-### Why it is bad
+### Why is this bad?
 - The lint name could be misspelled, leading to confusion as to why it is
   not working as expected
 - The unknown lint could end up causing an error if `cargo` decides to make

src/cargo/diagnostics/rules/unused_dependencies.rs

@@ -42,7 +42,7 @@ pub static LINT: &Lint = &Lint {
 
 Checks for dependencies that are not used by any of the cargo targets.
 
-### Why it is bad
+### Why is this bad?
 
 Slows down compilation time.
 

src/cargo/diagnostics/rules/unused_workspace_dependencies.rs

@@ -31,7 +31,7 @@ pub static LINT: &Lint = &Lint {
 ### What it does
 Checks for any entry in `[workspace.dependencies]` that has not been inherited
 
-### Why it is bad
+### Why is this bad?
 They can give the false impression that these dependencies are used
 
 ### Example

src/cargo/diagnostics/rules/unused_workspace_package_fields.rs

@@ -30,7 +30,7 @@ pub static LINT: &Lint = &Lint {
 ### What it does
 Checks for any fields in `[workspace.package]` that has not been inherited
 
-### Why it is bad
+### Why is this bad?
 They can give the false impression that these fields are used
 
 ### Example

src/doc/src/reference/lints.md

@@ -55,7 +55,7 @@ These lints are all set to the 'deny' level by default.
 ### What it does
 Checks if `hint-mostly-unused` being applied to all dependencies.
 
-### Why it is bad
+### Why is this bad?
 `hint-mostly-unused` indicates that most of a crate's API surface will go
 unused by anything depending on it; this hint can speed up the build by
 attempting to minimize compilation time for items that aren't used at all.
@@ -92,7 +92,7 @@ such as `serde = "1"` or `serde = "1.0"`.
 This lint currently only applies to caret requirements
 (the [default requirements](specifying-dependencies.md#default-requirements)).
 
-### Why it is bad
+### Why is this bad?
 
 Version requirements without an explicit full version
 can be misleading about the actual minimum supported version.
@@ -140,7 +140,7 @@ serde = "1.0.219"
 
 Checks for packages without a `lints` table while `workspace.lints` is present.
 
-### Why it is bad
+### Why is this bad?
 
 Many people mistakenly think that `workspace.lints` is implicitly inherited when it is not.
 
@@ -181,7 +181,7 @@ or make it explicit that you don't intend to inherit by adding an empty `[lints]
 
 Detect binary names, explicit and implicit, that are not kebab-case
 
-### Why it is bad
+### Why is this bad?
 
 Kebab-case binary names is a common convention among command line tools.
 
@@ -218,7 +218,7 @@ name = "foo-bar"
 
 Detect feature names that are not kebab-case.
 
-### Why it is bad
+### Why restrict this?
 
 Having multiple naming styles within a workspace can be confusing.
 
@@ -251,7 +251,7 @@ foo-bar = []
 
 Detect package names that are not kebab-case.
 
-### Why it is bad
+### Why restrict this?
 
 Having multiple naming styles within a workspace can be confusing.
 
@@ -284,7 +284,7 @@ name = "foo-bar"
 
 Detect feature names that are not snake-case.
 
-### Why it is bad
+### Why restrict this?
 
 Having multiple naming styles within a workspace can be confusing.
 
@@ -317,7 +317,7 @@ foo_bar = []
 
 Detect package names that are not snake-case.
 
-### Why it is bad
+### Why restrict this?
 
 Having multiple naming styles within a workspace can be confusing.
 
@@ -353,7 +353,7 @@ Checks if the value of `package.homepage` is already covered by another field.
 
 See also [`package.homepage` reference documentation](manifest.md#the-homepage-field).
 
-### Why it is bad
+### Why is this bad?
 
 When package browsers render each link, a redundant link adds visual noise.
 
@@ -390,7 +390,7 @@ Checks for `package.readme` fields that can be inferred.
 
 See also [`package.readme` reference documentation](manifest.md#the-readme-field).
 
-### Why it is bad
+### Why is this bad?
 
 Adds boilerplate.
 
@@ -425,7 +425,7 @@ name = "foo"
 Detects Unicode codepoints in manifest comments that change the visual representation of text on screen
 in a way that does not correspond to their on memory representation.
 
-### Why it is bad
+### Why is this bad?
 Unicode allows changing the visual flow of text on screen
 in order to support scripts that are written right-to-left,
 but a specially crafted comment can make code that will be compiled appear to be part of a comment,
@@ -446,7 +446,7 @@ by default we deny their use.
 Detects Unicode codepoints in literals in manifests that change the visual representation of text on screen
 in a way that does not correspond to their on memory representation.
 
-### Why it is bad
+### Why is this bad?
 Unicode allows changing the visual flow of text on screen
 in order to support scripts that are written right-to-left,
 but a specially crafted literal can make code that will be compiled appear to be part of a literal,
@@ -466,7 +466,7 @@ by default we deny their use.
 ### What it does
 Checks for unknown lints in the `[lints.cargo]` table
 
-### Why it is bad
+### Why is this bad?
 - The lint name could be misspelled, leading to confusion as to why it is
   not working as expected
 - The unknown lint could end up causing an error if `cargo` decides to make
@@ -490,7 +490,7 @@ this-lint-does-not-exist = "warn"
 
 Checks for dependencies that are not used by any of the cargo targets.
 
-### Why it is bad
+### Why is this bad?
 
 Slows down compilation time.
 
@@ -543,7 +543,7 @@ name = "foo"
 ### What it does
 Checks for any entry in `[workspace.dependencies]` that has not been inherited
 
-### Why it is bad
+### Why is this bad?
 They can give the false impression that these dependencies are used
 
 ### Example
@@ -565,7 +565,7 @@ regex = "1"
 ### What it does
 Checks for any fields in `[workspace.package]` that has not been inherited
 
-### Why it is bad
+### Why is this bad?
 They can give the false impression that these fields are used
 
 ### Example