For restriction lints, replace “Why is this bad?” with “Why restrict this?”

The `restriction` group contains many lints which are not about
necessarily “bad” things, but style choices — perhaps even style choices
which contradict conventional Rust style — or are otherwise very
situational. This results in silly wording like “Why is this bad?
It isn't, but ...”, which I’ve seen confuse a newcomer at least once.

To improve this situation, this commit replaces the “Why is this bad?”
section heading with “Why restrict this?”, for most, but not all,
restriction lints. I left alone the ones whose placement in the
restriction group is more incidental.

In order to make this make sense, I had to remove the “It isn't, but”
texts from the contents of the sections. Sometimes further changes
were needed, or there were obvious fixes to make, and I went ahead
and made those changes without attempting to split them into another
commit, even though many of them are not strictly necessary for the
“Why restrict this?” project.

book/src/development/adding_lints.md

@@ -587,6 +587,11 @@ declare_clippy_lint! {
 }
 ```
 
+If the lint is in the `restriction` group because it lints things that are not
+necessarily “bad” but are more of a style choice, then replace the
+“Why is this bad?” section heading with “Why restrict this?”, to avoid writing
+“Why is this bad? It isn't, but ...”.
+
 Once your lint is merged, this documentation will show up in the [lint
 list][lint_list].
 

clippy_dev/src/new_lint.rs

@@ -331,12 +331,17 @@ fn get_lint_file_contents(lint: &LintData<'_>, enable_msrv: bool) -> String {
 }
 
 fn get_lint_declaration(name_upper: &str, category: &str) -> String {
+    let justification_heading = if category == "restriction" {
+        "Why restrict this?"
+    } else {
+        "Why is this bad?"
+    };
     formatdoc!(
         r#"
             declare_clippy_lint! {{
                 /// ### What it does
                 ///
-                /// ### Why is this bad?
+                /// ### {justification_heading}
                 ///
                 /// ### Example
                 /// ```no_run

clippy_lints/src/absolute_paths.rs

@@ -12,7 +12,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of items through absolute paths, like `std::env::current_dir`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Many codebases have their own style when it comes to importing, but one that is seldom used
     /// is using absolute paths *everywhere*. This is generally considered unidiomatic, and you
     /// should add a `use` statement.

clippy_lints/src/allow_attributes.rs

@@ -19,10 +19,11 @@ declare_clippy_lint! {
     /// This lint only warns outer attributes (`#[allow]`), as inner attributes
     /// (`#![allow]`) are usually used to enable or disable lints on a global scale.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// `#[expect]` attributes suppress the lint emission, but emit a warning, if
+    /// `#[allow]` attributes can linger after their reason for existence is gone.
+    /// `#[expect]` attributes suppress the lint emission, but emit a warning if
     /// the expectation is unfulfilled. This can be useful to be notified when the
-    /// lint is no longer triggered.
+    /// lint is no longer triggered, which may indicate the attribute can be removed.
     ///
     /// ### Example
     /// ```rust,ignore

clippy_lints/src/as_conversions.rs

@@ -17,7 +17,7 @@ declare_clippy_lint! {
     /// There is a good explanation the reason why this lint should work in this way and how it is useful
     /// [in this issue](https://github.com/rust-lang/rust-clippy/issues/5122).
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// `as` conversions will perform many kinds of
     /// conversions, including silently lossy conversions and dangerous coercions.
     /// There are cases when it makes sense to use `as`, so the lint is

clippy_lints/src/asm_syntax.rs

@@ -65,9 +65,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of Intel x86 assembly syntax.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// The lint has been enabled to indicate a preference
+    /// To enforce consistent use of AT&T x86 assembly syntax.
-    /// for AT&T x86 assembly syntax.
     ///
     /// ### Example
     ///
@@ -114,9 +113,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of AT&T x86 assembly syntax.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// The lint has been enabled to indicate a preference
+    /// To enforce consistent use of Intel x86 assembly syntax.
-    /// for Intel x86 assembly syntax.
     ///
     /// ### Example
     ///

clippy_lints/src/assertions_on_result_states.rs

@@ -16,23 +16,33 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `assert!(r.is_ok())` or `assert!(r.is_err())` calls.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// An assertion failure cannot output an useful message of the error.
+    /// This form of assertion does not show any of the information present in the `Result`
+    /// other than which variant it isn’t.
     ///
     /// ### Known problems
     /// The suggested replacement decreases the readability of code and log output.
     ///
     /// ### Example
-    /// ```rust,ignore
+    /// ```rust,no_run
     /// # let r = Ok::<_, ()>(());
     /// assert!(r.is_ok());
-    /// # let r = Err::<_, ()>(());
+    /// # let r = Err::<(), _>(());
     /// assert!(r.is_err());
     /// ```
+    ///
+    /// Use instead:
+    ///
+    /// ```rust,no_run
+    /// # let r = Ok::<_, ()>(());
+    /// r.unwrap();
+    /// # let r = Err::<(), _>(());
+    /// r.unwrap_err();
+    /// ```
     #[clippy::version = "1.64.0"]
     pub ASSERTIONS_ON_RESULT_STATES,
     restriction,
-    "`assert!(r.is_ok())`/`assert!(r.is_err())` gives worse error message than directly calling `r.unwrap()`/`r.unwrap_err()`"
+    "`assert!(r.is_ok())` or `assert!(r.is_err())` gives worse panic messages than directly calling `r.unwrap()` or `r.unwrap_err()`"
 }
 
 declare_lint_pass!(AssertionsOnResultStates => [ASSERTIONS_ON_RESULT_STATES]);

clippy_lints/src/attrs/mod.rs

@@ -309,9 +309,9 @@ declare_clippy_lint! {
     ///
     /// (This requires the `lint_reasons` feature)
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Allowing a lint should always have a reason. This reason should be documented to
+    /// Justifying each `allow` helps readers understand the reasoning,
-    /// ensure that others understand the reasoning
+    /// and may allow removing `allow` attributes if their purpose is obsolete.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/casts/mod.rs

@@ -303,7 +303,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for casts of a function pointer to any integer type.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Casting a function pointer to an integer can have surprising results and can occur
     /// accidentally if parentheses are omitted from a function call. If you aren't doing anything
     /// low-level with function pointers then you can opt-out of casting functions to integers in
@@ -535,8 +535,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for the usage of `as _` conversion using inferred type.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// The conversion might include lossy conversion and dangerous cast that might go
+    /// The conversion might include lossy conversion or a dangerous cast that might go
     /// undetected due to the type being inferred.
     ///
     /// The lint is allowed by default as using `_` is less wordy than always specifying the type.

clippy_lints/src/create_dir.rs

@@ -10,8 +10,10 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks usage of `std::fs::create_dir` and suggest using `std::fs::create_dir_all` instead.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`.
+    /// Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`,
+    /// resulting in failure when more than one directory needs to be created or when the directory already exists.
+    /// Crates which never need to specifically create a single directory may wish to prevent this mistake.
     ///
     /// ### Example
     /// ```rust,ignore

clippy_lints/src/dbg_macro.rs

@@ -14,7 +14,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of the [`dbg!`](https://doc.rust-lang.org/std/macro.dbg.html) macro.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// The `dbg!` macro is intended as a debugging tool. It should not be present in released
     /// software or committed to a version control system.
     ///

clippy_lints/src/default_numeric_fallback.rs

@@ -22,9 +22,8 @@ declare_clippy_lint! {
     ///
     /// See [RFC0212](https://github.com/rust-lang/rfcs/blob/master/text/0212-restore-int-fallback.md) for more information about the fallback.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// For those who are very careful about types, default numeric fallback
+    /// To ensure that every numeric type is chosen explicitly rather than implicitly.
-    /// can be a pitfall that cause unexpected runtime behavior.
     ///
     /// ### Known problems
     /// This lint can only be allowed at the function level or above.

clippy_lints/src/default_union_representation.rs

@@ -10,7 +10,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Displays a warning when a union is declared with the default representation (without a `#[repr(C)]` attribute).
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Unions in Rust have unspecified layout by default, despite many people thinking that they
     /// lay out each field at the start of the union (like C does). That is, there are no guarantees
     /// about the offset of the fields for unions with multiple non-ZST fields without an explicitly

clippy_lints/src/disallowed_script_idents.rs

@@ -20,11 +20,11 @@ declare_clippy_lint! {
     /// [aliases]: http://www.unicode.org/reports/tr24/tr24-31.html#Script_Value_Aliases
     /// [supported_scripts]: https://www.unicode.org/iso15924/iso15924-codes.html
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// It may be not desired to have many different scripts for
     /// identifiers in the codebase.
     ///
-    /// Note that if you only want to allow plain English, you might want to use
+    /// Note that if you only want to allow typical English, you might want to use
     /// built-in [`non_ascii_idents`] lint instead.
     ///
     /// [`non_ascii_idents`]: https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#non-ascii-idents

clippy_lints/src/doc/mod.rs

@@ -261,7 +261,7 @@ declare_clippy_lint! {
     /// Checks for the doc comments of publicly visible
     /// safe functions and traits and warns if there is a `# Safety` section.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Safe functions and traits are safe to implement and therefore do not
     /// need to describe safety preconditions that users are required to uphold.
     ///

clippy_lints/src/drop_forget_ref.rs

@@ -52,9 +52,10 @@ declare_clippy_lint! {
     /// Checks for usage of `std::mem::forget(t)` where `t` is
     /// `Drop` or has a field that implements `Drop`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// `std::mem::forget(t)` prevents `t` from running its
+    /// `std::mem::forget(t)` prevents `t` from running its destructor, possibly causing leaks.
-    /// destructor, possibly causing leaks.
+    /// It is not possible to detect all means of creating leaks, but it may be desirable to
+    /// prohibit the simple ones.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/else_if_without_else.rs

@@ -11,7 +11,7 @@ declare_clippy_lint! {
     /// Checks for usage of if expressions with an `else if` branch,
     /// but without a final `else` branch.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Some coding guidelines require this (e.g., MISRA-C:2004 Rule 14.10).
     ///
     /// ### Example

clippy_lints/src/empty_drop.rs

@@ -9,7 +9,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for empty `Drop` implementations.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Empty `Drop` implementations have no effect when dropping an instance of the type. They are
     /// most likely useless. However, an empty `Drop` implementation prevents a type from being
     /// destructured, which might be the intention behind adding the implementation as a marker.

clippy_lints/src/empty_with_brackets.rs

@@ -11,16 +11,23 @@ declare_clippy_lint! {
     /// ### What it does
     /// Finds structs without fields (a so-called "empty struct") that are declared with brackets.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Empty brackets after a struct declaration can be omitted.
+    /// Empty brackets after a struct declaration can be omitted,
+    /// and it may be desirable to do so consistently for style.
+    ///
+    /// However, removing the brackets also introduces a public constant named after the struct,
+    /// so this is not just a syntactic simplification but an an API change, and adding them back
+    /// is a *breaking* API change.
     ///
     /// ### Example
     /// ```no_run
     /// struct Cookie {}
+    /// struct Biscuit();
     /// ```
     /// Use instead:
     /// ```no_run
     /// struct Cookie;
+    /// struct Biscuit;
     /// ```
     #[clippy::version = "1.62.0"]
     pub EMPTY_STRUCTS_WITH_BRACKETS,
@@ -32,14 +39,20 @@ declare_clippy_lint! {
     /// ### What it does
     /// Finds enum variants without fields that are declared with empty brackets.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Empty brackets while defining enum variants are redundant and can be omitted.
+    /// Empty brackets after a enum variant declaration are redundant and can be omitted,
+    /// and it may be desirable to do so consistently for style.
+    ///
+    /// However, removing the brackets also introduces a public constant named after the variant,
+    /// so this is not just a syntactic simplification but an an API change, and adding them back
+    /// is a *breaking* API change.
     ///
     /// ### Example
     /// ```no_run
     /// enum MyEnum {
     ///     HasData(u8),
     ///     HasNoData(),       // redundant parentheses
+    ///     NoneHereEither {}, // redundant braces
     /// }
     /// ```
     ///
@@ -48,6 +61,7 @@ declare_clippy_lint! {
     /// enum MyEnum {
     ///     HasData(u8),
     ///     HasNoData,
+    ///     NoneHereEither,
     /// }
     /// ```
     #[clippy::version = "1.77.0"]

clippy_lints/src/endian_bytes.rs

@@ -13,8 +13,9 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for the usage of the `to_ne_bytes` method and/or the function `from_ne_bytes`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It's not, but some may prefer to specify the target endianness explicitly.
+    /// To ensure use of explicitly chosen endianness rather than the target’s endianness,
+    /// such as when implementing network protocols or file formats rather than FFI.
     ///
     /// ### Example
     /// ```rust,ignore
@@ -31,9 +32,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for the usage of the `to_le_bytes` method and/or the function `from_le_bytes`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It's not, but some may wish to lint usage of this method, either to suggest using the host
+    /// To ensure use of big endian or the target’s endianness rather than little endian.
-    /// endianness or big endian.
     ///
     /// ### Example
     /// ```rust,ignore
@@ -50,9 +50,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for the usage of the `to_be_bytes` method and/or the function `from_be_bytes`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It's not, but some may wish to lint usage of this method, either to suggest using the host
+    /// To ensure use of little endian or the target’s endianness rather than big endian.
-    /// endianness or little endian.
     ///
     /// ### Example
     /// ```rust,ignore

clippy_lints/src/error_impl_error.rs

@@ -12,7 +12,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for types named `Error` that implement `Error`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// It can become confusing when a codebase has 20 types all named `Error`, requiring either
     /// aliasing them in the `use` statement or qualifying them like `my_module::Error`. This
     /// hinders comprehension, as it requires you to memorize every variation of importing `Error`

clippy_lints/src/exhaustive_items.rs

@@ -10,10 +10,10 @@ declare_clippy_lint! {
     /// ### What it does
     /// Warns on any exported `enum`s that are not tagged `#[non_exhaustive]`
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Exhaustive enums are typically fine, but a project which does
+    /// Making an `enum` exhaustive is a stability commitment: adding a variant is a breaking change.
-    /// not wish to make a stability commitment around exported enums may wish to
+    /// A project may wish to ensure that there are no exhaustive enums or that every exhaustive
-    /// disable them by default.
+    /// `enum` is explicitly `#[allow]`ed.
     ///
     /// ### Example
     /// ```no_run
@@ -40,10 +40,10 @@ declare_clippy_lint! {
     /// ### What it does
     /// Warns on any exported `struct`s that are not tagged `#[non_exhaustive]`
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Exhaustive structs are typically fine, but a project which does
+    /// Making a `struct` exhaustive is a stability commitment: adding a field is a breaking change.
-    /// not wish to make a stability commitment around exported structs may wish to
+    /// A project may wish to ensure that there are no exhaustive structs or that every exhaustive
-    /// disable them by default.
+    /// `struct` is explicitly `#[allow]`ed.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/exit.rs

@@ -9,11 +9,13 @@ declare_clippy_lint! {
     /// ### What it does
     /// Detects calls to the `exit()` function which terminates the program.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Exit terminates the program at the location it is called. For unrecoverable
+    /// `exit()` immediately terminates the program with no information other than an exit code.
-    /// errors `panics` should be used to provide a stacktrace and potentially other
+    /// This provides no means to troubleshoot a problem, and may be an unexpected side effect.
-    /// information. A normal termination or one with an error code should happen in
+    ///
-    /// the main function.
+    /// Codebases may use this lint to require that all exits are performed either by panicking
+    /// (which produces a message, a code location, and optionally a backtrace)
+    /// or by returning from `main()` (which is a single place to look).
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/float_literal.rs

@@ -38,9 +38,9 @@ declare_clippy_lint! {
     /// Checks for whole number float literals that
     /// cannot be represented as the underlying type without loss.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Rust will silently lose precision during
+    /// If the value was intended to be exact, it will not be.
-    /// conversion to a float.
+    /// This may be especially surprising when the lost precision is to the left of the decimal point.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/format_push_string.rs

@@ -11,7 +11,7 @@ declare_clippy_lint! {
     /// Detects cases where the result of a `format!` call is
     /// appended to an existing `String`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Introduces an extra, avoidable heap allocation.
     ///
     /// ### Known problems

clippy_lints/src/functions/mod.rs

@@ -338,8 +338,10 @@ declare_clippy_lint! {
 declare_clippy_lint! {
     /// ### What it does
     /// Lints when `impl Trait` is being used in a function's parameters.
-    /// ### Why is this bad?
+    ///
-    /// Turbofish syntax (`::<>`) cannot be used when `impl Trait` is being used, making `impl Trait` less powerful. Readability may also be a factor.
+    /// ### Why restrict this?
+    /// Turbofish syntax (`::<>`) cannot be used to specify the type of an `impl Trait` parameter,
+    /// making `impl Trait` less powerful. Readability may also be a factor.
     ///
     /// ### Example
     /// ```no_run
@@ -366,9 +368,8 @@ declare_clippy_lint! {
     /// Lints when the name of function parameters from trait impl is
     /// different than its default implementation.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Using the default name for parameters of a trait method is often
+    /// Using the default name for parameters of a trait method is more consistent.
-    /// more desirable for consistency's sake.
     ///
     /// ### Example
     /// ```rust

clippy_lints/src/if_then_some_else_none.rs

@@ -15,7 +15,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for if-else that could be written using either `bool::then` or `bool::then_some`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Looks a little redundant. Using `bool::then` is more concise and incurs no loss of clarity.
     /// For simple calculations and known values, use `bool::then_some`, which is eagerly evaluated
     /// in comparison to `bool::then`.

clippy_lints/src/implicit_return.rs

@@ -16,11 +16,12 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for missing return statements at the end of a block.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Actually omitting the return keyword is idiomatic Rust code. Programmers
+    /// Omitting the return keyword whenever possible is idiomatic Rust code, but:
-    /// coming from other languages might prefer the expressiveness of `return`. It's possible to miss
+    ///
-    /// the last returning statement because the only difference is a missing `;`. Especially in bigger
+    /// * Programmers coming from other languages might prefer the expressiveness of `return`.
-    /// code with multiple return paths having a `return` keyword makes it easier to find the
+    /// * It's possible to miss the last returning statement because the only difference is a missing `;`.
+    /// * Especially in bigger code with multiple return paths, having a `return` keyword makes it easier to find the
     ///   corresponding statements.
     ///
     /// ### Example

clippy_lints/src/indexing_slicing.rs

@@ -45,9 +45,10 @@ declare_clippy_lint! {
     /// does report on arrays if we can tell that slicing operations are in bounds and does not
     /// lint on constant `usize` indexing on arrays because that is handled by rustc's `const_err` lint.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Indexing and slicing can panic at runtime and there are
+    /// To avoid implicit panics from indexing and slicing.
-    /// safe alternatives.
+    /// There are “checked” alternatives which do not panic, and can be used with `unwrap()` to make
+    /// an explicit panic when it is desired.
     ///
     /// ### Example
     /// ```rust,no_run

clippy_lints/src/inherent_impl.rs

@@ -14,7 +14,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for multiple inherent implementations of a struct
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Splitting the implementation of a type makes the code harder to navigate.
     ///
     /// ### Example

clippy_lints/src/integer_division_remainder_used.rs

@@ -7,10 +7,10 @@ use rustc_session::declare_lint_pass;
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for the usage of division (/) and remainder (%) operations
+    /// Checks for the usage of division (`/`) and remainder (`%`) operations
-    /// when performed on any integer types using the default Div and Rem trait implementations.
+    /// when performed on any integer types using the default `Div` and `Rem` trait implementations.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// In cryptographic contexts, division can result in timing sidechannel vulnerabilities,
     /// and needs to be replaced with constant-time code instead (e.g. Barrett reduction).
     ///

clippy_lints/src/iter_over_hash_type.rs

@@ -14,8 +14,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// This is a restriction lint which prevents the use of hash types (i.e., `HashSet` and `HashMap`) in for loops.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Because hash types are unordered, when iterated through such as in a for loop, the values are returned in
+    /// Because hash types are unordered, when iterated through such as in a `for` loop, the values are returned in
     /// an undefined order. As a result, on redundant systems this may cause inconsistencies and anomalies.
     /// In addition, the unknown order of the elements may reduce readability or introduce other undesired
     /// side effects.

clippy_lints/src/large_include_file.rs

@@ -10,10 +10,12 @@ use rustc_span::sym;
 declare_clippy_lint! {
     /// ### What it does
     /// Checks for the inclusion of large files via `include_bytes!()`
-    /// and `include_str!()`
+    /// or `include_str!()`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Including large files can increase the size of the binary
+    /// Including large files can undesirably increase the size of the binary produced by the compiler.
+    /// This lint may be used to catch mistakes where an unexpectedly large file is included, or
+    /// temporarily to obtain a list of all large files.
     ///
     /// ### Example
     /// ```rust,ignore

clippy_lints/src/let_underscore.rs

@@ -12,9 +12,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `let _ = <expr>` where expr is `#[must_use]`
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It's better to explicitly handle the value of a `#[must_use]`
+    /// To ensure that all `#[must_use]` types are used rather than ignored.
-    /// expr
     ///
     /// ### Example
     /// ```no_run
@@ -96,8 +95,8 @@ declare_clippy_lint! {
     /// Checks for `let _ = <expr>` without a type annotation, and suggests to either provide one,
     /// or remove the `let` keyword altogether.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// The `let _ = <expr>` expression ignores the value of `<expr>` but will remain doing so even
+    /// The `let _ = <expr>` expression ignores the value of `<expr>`, but will continue to do so even
     /// if the type were to change, thus potentially introducing subtle bugs. By supplying a type
     /// annotation, one will be forced to re-visit the decision to ignore the value in such cases.
     ///

clippy_lints/src/literal_representation.rs

@@ -132,8 +132,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Warns if there is a better representation for a numeric literal.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Especially for big powers of 2 a hexadecimal representation is more
+    /// Especially for big powers of 2, a hexadecimal representation is usually more
     /// readable than a decimal representation.
     ///
     /// ### Example

clippy_lints/src/loops/mod.rs

@@ -675,9 +675,9 @@ declare_clippy_lint! {
     /// Checks for infinite loops in a function where the return type is not `!`
     /// and lint accordingly.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// A loop should be gently exited somewhere, or at least mark its parent function as
+    /// Making the return type `!` serves as documentation that the function does not return.
-    /// never return (`!`).
+    /// If the function is not intended to loop infinitely, then this lint may detect a bug.
     ///
     /// ### Example
     /// ```no_run,ignore

clippy_lints/src/matches/mod.rs

@@ -260,7 +260,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for wildcard enum matches using `_`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// New enum variants added by library updates can be missed.
     ///
     /// ### Known problems
@@ -435,7 +435,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for unnecessary '..' pattern binding on struct when all fields are explicitly matched.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Correctness and readability. It's like having a wildcard pattern after
     /// matching all enum variants explicitly.
     ///
@@ -861,7 +861,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of `Err(x)?`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// The `?` operator is designed to allow calls that
     /// can fail to be easily chained. For example, `foo()?.bar()` or
     /// `foo(bar()?)`. Because `Err(x)?` can't be used that way (it will

clippy_lints/src/methods/mod.rs

@@ -257,7 +257,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `.unwrap()` or `.unwrap_err()` calls on `Result`s and `.unwrap()` call on `Option`s.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// It is better to handle the `None` or `Err` case,
     /// or at least call `.expect(_)` with a more helpful message. Still, for a lot of
     /// quick-and-dirty code, `unwrap` is a good choice, which is why this lint is
@@ -333,7 +333,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `.expect()` or `.expect_err()` calls on `Result`s and `.expect()` call on `Option`s.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Usually it is better to handle the `None` or `Err` case.
     /// Still, for a lot of quick-and-dirty code, `expect` is a good choice, which is why
     /// this lint is `Allow` by default.
@@ -1029,8 +1029,8 @@ declare_clippy_lint! {
     /// (`Rc`, `Arc`, `rc::Weak`, or `sync::Weak`), and suggests calling Clone via unified
     /// function syntax instead (e.g., `Rc::clone(foo)`).
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Calling '.clone()' on an Rc, Arc, or Weak
+    /// Calling `.clone()` on an `Rc`, `Arc`, or `Weak`
     /// can obscure the fact that only the pointer is being cloned, not the underlying
     /// data.
     ///
@@ -1051,7 +1051,7 @@ declare_clippy_lint! {
     #[clippy::version = "pre 1.29.0"]
     pub CLONE_ON_REF_PTR,
     restriction,
-    "using 'clone' on a ref-counted pointer"
+    "using `clone` on a ref-counted pointer"
 }
 
 declare_clippy_lint! {
@@ -1359,7 +1359,7 @@ declare_clippy_lint! {
     /// Checks for usage of `.get().unwrap()` (or
     /// `.get_mut().unwrap`) on a standard library type which implements `Index`
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Using the Index trait (`[]`) is more clear and more
     /// concise.
     ///
@@ -1743,7 +1743,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `FileType::is_file()`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// When people testing a file type with `FileType::is_file`
     /// they are testing whether a path is something they can get bytes from. But
     /// `is_file` doesn't cover special file types in unix-like systems, and doesn't cover
@@ -2688,8 +2688,9 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for instances of `map_err(|_| Some::Enum)`
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// This `map_err` throws away the original error rather than allowing the enum to contain and report the cause of the error
+    /// This `map_err` throws away the original error rather than allowing the enum to
+    /// contain and report the cause of the error.
     ///
     /// ### Example
     /// Before:
@@ -3145,7 +3146,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of File::read_to_end and File::read_to_string.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// `fs::{read, read_to_string}` provide the same functionality when `buf` is empty with fewer imports and no intermediate values.
     /// See also: [fs::read docs](https://doc.rust-lang.org/std/fs/fn.read.html), [fs::read_to_string docs](https://doc.rust-lang.org/std/fs/fn.read_to_string.html)
     ///

clippy_lints/src/min_ident_chars.rs

@@ -12,14 +12,13 @@ use std::borrow::Cow;
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for idents which comprise of a single letter.
+    /// Checks for identifiers which consist of a single character (or fewer than the configured threshold).
     ///
     /// Note: This lint can be very noisy when enabled; it may be desirable to only enable it
     /// temporarily.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// In many cases it's not, but at times it can severely hinder readability. Some codebases may
+    /// To improve readability by requiring that every variable has a name more specific than a single letter can be.
-    /// wish to disallow this to improve readability.
     ///
     /// ### Example
     /// ```rust,ignore

clippy_lints/src/misc_early/mod.rs

@@ -23,7 +23,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for structure field patterns bound to wildcards.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Using `..` instead is shorter and leaves the focus on
     /// the fields that are actually bound.
     ///
@@ -138,7 +138,7 @@ declare_clippy_lint! {
     /// To enforce unseparated literal suffix style,
     /// see the `separated_literal_suffix` lint.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Suffix style should be consistent.
     ///
     /// ### Example
@@ -166,7 +166,7 @@ declare_clippy_lint! {
     /// To enforce separated literal suffix style,
     /// see the `unseparated_literal_suffix` lint.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Suffix style should be consistent.
     ///
     /// ### Example

clippy_lints/src/missing_assert_message.rs

@@ -10,7 +10,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks assertions without a custom panic message.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Without a good custom message, it'd be hard to understand what went wrong when the assertion fails.
     /// A good custom message should be more about why the failure of the assertion is problematic
     /// and not what is failed because the assertion already conveys that.

clippy_lints/src/missing_asserts_for_indexing.rs

@@ -21,7 +21,7 @@ declare_clippy_lint! {
     /// Checks for repeated slice indexing without asserting beforehand that the length
     /// is greater than the largest index used to index into the slice.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// In the general case where the compiler does not have a lot of information
     /// about the length of a slice, indexing it repeatedly will generate a bounds check
     /// for every single index.

clippy_lints/src/missing_doc.rs

@@ -20,9 +20,9 @@ use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Warns if there is missing doc for any private documentable item
+    /// Warns if there is missing documentation for any private documentable item.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Doc is good. *rustc* has a `MISSING_DOCS`
     /// allowed-by-default lint for
     /// public members, but has no way to enforce documentation of private items.

clippy_lints/src/missing_inline.rs

@@ -10,13 +10,16 @@ declare_clippy_lint! {
     /// It lints if an exported function, method, trait method with default impl,
     /// or trait method impl is not `#[inline]`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// In general, it is not. Functions can be inlined across
+    /// When a function is not marked `#[inline]`, it is not
-    /// crates when that's profitable as long as any form of LTO is used. When LTO is disabled,
+    /// [a “small” candidate for automatic inlining][small], and LTO is not in use, then it is not
-    /// functions that are not `#[inline]` cannot be inlined across crates. Certain types of crates
+    /// possible for the function to be inlined into the code of any crate other than the one in
-    /// might intend for most of the methods in their public API to be able to be inlined across
+    /// which it is defined.  Depending on the role of the function and the relationship of the crates,
-    /// crates even when LTO is disabled. For these types of crates, enabling this lint might make
+    /// this could significantly reduce performance.
-    /// sense. It allows the crate to require all exported methods to be `#[inline]` by default, and
+    ///
+    /// Certain types of crates might intend for most of the methods in their public API to be able
+    /// to be inlined across crates even when LTO is disabled.
+    /// This lint allows those crates to require all exported methods to be `#[inline]` by default, and
     /// then opt out for specific methods where this might not make sense.
     ///
     /// ### Example
@@ -51,6 +54,8 @@ declare_clippy_lint! {
     ///    fn def_bar() {} // missing #[inline]
     /// }
     /// ```
+    ///
+    /// [small]: https://github.com/rust-lang/rust/pull/116505
     #[clippy::version = "pre 1.29.0"]
     pub MISSING_INLINE_IN_PUBLIC_ITEMS,
     restriction,

clippy_lints/src/missing_trait_methods.rs

@@ -10,16 +10,16 @@ use rustc_session::declare_lint_pass;
 declare_clippy_lint! {
     /// ### What it does
     /// Checks if a provided method is used implicitly by a trait
-    /// implementation. A usage example would be a wrapper where every method
-    /// should perform some operation before delegating to the inner type's
     /// implementation.
     ///
+    /// ### Why restrict this?
+    /// To ensure that a certain implementation implements every method; for example,
+    /// a wrapper type where every method should delegate to the corresponding method of
+    /// the inner type's implementation.
+    ///
     /// This lint should typically be enabled on a specific trait `impl` item
     /// rather than globally.
     ///
-    /// ### Why is this bad?
-    /// Indicates that a method is missing.
-    ///
     /// ### Example
     /// ```no_run
     /// trait Trait {

clippy_lints/src/mixed_read_write_in_expression.rs

@@ -12,9 +12,10 @@ declare_clippy_lint! {
     /// whether the read occurs before or after the write depends on the evaluation
     /// order of sub-expressions.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It is often confusing to read. As described [here](https://doc.rust-lang.org/reference/expressions.html?highlight=subexpression#evaluation-order-of-operands),
+    /// While [the evaluation order of sub-expressions] is fully specified in Rust,
-    /// the operands of these expressions are evaluated before applying the effects of the expression.
+    /// it still may be confusing to read an expression where the evaluation order
+    /// affects its behavior.
     ///
     /// ### Known problems
     /// Code which intentionally depends on the evaluation
@@ -40,6 +41,8 @@ declare_clippy_lint! {
     /// };
     /// let a = tmp + x;
     /// ```
+    ///
+    /// [order]: (https://doc.rust-lang.org/reference/expressions.html?highlight=subexpression#evaluation-order-of-operands)
     #[clippy::version = "pre 1.29.0"]
     pub MIXED_READ_WRITE_IN_EXPRESSION,
     restriction,

clippy_lints/src/module_style.rs

@@ -10,9 +10,9 @@ use std::path::{Component, Path};
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks that module layout uses only self named module files, bans `mod.rs` files.
+    /// Checks that module layout uses only self named module files; bans `mod.rs` files.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Having multiple module layout styles in a project can be confusing.
     ///
     /// ### Example
@@ -41,7 +41,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks that module layout uses only `mod.rs` files.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Having multiple module layout styles in a project can be confusing.
     ///
     /// ### Example

clippy_lints/src/multiple_unsafe_ops_per_block.rs

@@ -15,7 +15,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `unsafe` blocks that contain more than one unsafe operation.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Combined with `undocumented_unsafe_blocks`,
     /// this lint ensures that each unsafe operation must be independently justified.
     /// Combined with `unused_unsafe`, this lint also ensures

clippy_lints/src/mutex_atomic.rs

@@ -14,7 +14,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of `Mutex<X>` where an atomic will do.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Using a mutex just to make access to a plain bool or
     /// reference sequential is shooting flies with cannons.
     /// `std::sync::atomic::AtomicBool` and `std::sync::atomic::AtomicPtr` are leaner and

clippy_lints/src/operators/mod.rs

@@ -70,7 +70,7 @@ declare_clippy_lint! {
     /// Known safe built-in types like `Wrapping` or `Saturating`, floats, operations in constant
     /// environments, allowed types and non-constant operations that won't overflow are ignored.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// For integers, overflow will trigger a panic in debug builds or wrap the result in
     /// release mode; division by zero will cause a panic in either mode. As a result, it is
     /// desirable to explicitly call checked, wrapping or saturating arithmetic methods.
@@ -100,7 +100,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for float arithmetic.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// For some embedded systems or kernel development, it
     /// can be useful to rule out floating-point numbers.
     ///
@@ -502,7 +502,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for division of integers
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// When outside of some very specific algorithms,
     /// integer division is very often a mistake because it discards the
     /// remainder.
@@ -596,7 +596,7 @@ declare_clippy_lint! {
     /// value and constant, except in functions called `*eq*` (which probably
     /// implement equality for a type involving floats).
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Floating point calculations are usually imprecise, so
     /// asking if two values are *exactly* equal is asking for trouble. For a good
     /// guide on what to do, see [the floating point
@@ -653,8 +653,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for modulo arithmetic.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// The results of modulo (%) operation might differ
+    /// The results of modulo (`%`) operation might differ
     /// depending on the language, when negative numbers are involved.
     /// If you interop with different languages it might be beneficial
     /// to double check all places that use modulo arithmetic.

clippy_lints/src/panic_in_result_fn.rs

@@ -13,9 +13,9 @@ use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks for usage of `panic!` or assertions in a function of type result.
+    /// Checks for usage of `panic!` or assertions in a function whose return type is `Result`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// For some codebases, it is desirable for functions of type result to return an error instead of crashing. Hence panicking macros should be avoided.
     ///
     /// ### Known problems

clippy_lints/src/panic_unimplemented.rs

@@ -14,8 +14,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of `panic!`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// `panic!` will stop the execution of the executable.
+    /// This macro, or panics in general, may be unwanted in production code.
     ///
     /// ### Example
     /// ```no_run
@@ -31,8 +31,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of `unimplemented!`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// This macro should not be present in production code.
+    /// This macro, or panics in general, may be unwanted in production code.
     ///
     /// ### Example
     /// ```no_run
@@ -48,9 +48,9 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of `todo!`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// The `todo!` macro is often used for unfinished code, and it causes
+    /// The `todo!` macro indicates the presence of unfinished code,
-    /// code to panic. It should not be present in production code.
+    /// so it should not be present in production code.
     ///
     /// ### Example
     /// ```no_run
@@ -70,8 +70,8 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of `unreachable!`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// This macro can cause code to panic.
+    /// This macro, or panics in general, may be unwanted in production code.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/partial_pub_fields.rs

@@ -5,15 +5,16 @@ use rustc_session::declare_lint_pass;
 
 declare_clippy_lint! {
     /// ### What it does
-    /// Checks whether partial fields of a struct are public.
+    /// Checks whether some but not all fields of a `struct` are public.
     ///
     /// Either make all fields of a type public, or make none of them public
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Most types should either be:
     /// * Abstract data types: complex objects with opaque implementation which guard
     ///   interior invariants and expose intentionally limited API to the outside world.
-    /// * Data: relatively simple objects which group a bunch of related attributes together.
+    /// * Data: relatively simple objects which group a bunch of related attributes together,
+    ///   but have no invariants.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/pattern_type_mismatch.rs

@@ -30,9 +30,8 @@ declare_clippy_lint! {
     /// this lint can still be used to highlight areas of interest and ensure a good understanding
     /// of ownership semantics.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It isn't bad in general. But in some contexts it can be desirable
+    /// It increases ownership hints in the code, and will guard against some changes
-    /// because it increases ownership hints in the code, and will guard against some changes
     /// in ownership.
     ///
     /// ### Example

clippy_lints/src/pub_use.rs

@@ -5,13 +5,11 @@ use rustc_session::declare_lint_pass;
 
 declare_clippy_lint! {
     /// ### What it does
-    ///
     /// Restricts the usage of `pub use ...`
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    ///
+    /// A project may wish to limit `pub use` instances to prevent
-    /// `pub use` is usually fine, but a project may wish to limit `pub use` instances to prevent
+    /// unintentional exports, or to encourage placing exported items directly in public modules.
-    /// unintentional exports or to encourage placing exported items directly in public modules
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/question_mark_used.rs

@@ -9,7 +9,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for expressions that use the question mark operator and rejects them.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Sometimes code wants to avoid the question mark operator because for instance a local
     /// block requires a macro to re-throw errors to attach additional information to the
     /// error.

clippy_lints/src/raw_strings.rs

@@ -15,8 +15,10 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for raw string literals where a string literal can be used instead.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It's just unnecessary, but there are many cases where using a raw string literal is more
+    /// For consistent style by using simpler string literals whenever possible.
+    ///
+    /// However, there are many cases where using a raw string literal is more
     /// idiomatic than a string literal, so it's opt-in.
     ///
     /// ### Example

clippy_lints/src/redundant_slicing.rs

@@ -46,7 +46,7 @@ declare_clippy_lint! {
     /// Checks for slicing expressions which are equivalent to dereferencing the
     /// value.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Some people may prefer to dereference rather than slice.
     ///
     /// ### Example

clippy_lints/src/redundant_type_annotations.rs

@@ -11,7 +11,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Warns about needless / redundant type annotations.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Code without type annotations is shorter and in most cases
     /// more idiomatic and easier to modify.
     ///

clippy_lints/src/ref_patterns.rs

@@ -6,9 +6,11 @@ use rustc_session::declare_lint_pass;
 declare_clippy_lint! {
     /// ### What it does
     /// Checks for usages of the `ref` keyword.
-    /// ### Why is this bad?
+    ///
+    /// ### Why restrict this?
     /// The `ref` keyword can be confusing for people unfamiliar with it, and often
     /// it is more concise to use `&` instead.
+    ///
     /// ### Example
     /// ```no_run
     /// let opt = Some(5);

clippy_lints/src/same_name_method.rs

@@ -14,7 +14,7 @@ declare_clippy_lint! {
     /// It lints if a struct has two methods with the same name:
     /// one from a trait, another not from trait.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Confusing.
     ///
     /// ### Example

clippy_lints/src/semicolon_block.rs

@@ -11,8 +11,7 @@ declare_clippy_lint! {
     /// Suggests moving the semicolon after a block to the inside of the block, after its last
     /// expression.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    ///
     /// For consistency it's best to have the semicolon inside/outside the block. Either way is fine
     /// and this lint suggests inside the block.
     /// Take a look at `semicolon_outside_block` for the other alternative.
@@ -40,8 +39,7 @@ declare_clippy_lint! {
     ///
     /// Suggests moving the semicolon from a block's final expression outside of the block.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    ///
     /// For consistency it's best to have the semicolon inside/outside the block. Either way is fine
     /// and this lint suggests outside the block.
     /// Take a look at `semicolon_inside_block` for the other alternative.

clippy_lints/src/shadow.rs

@@ -15,10 +15,10 @@ declare_clippy_lint! {
     /// Checks for bindings that shadow other bindings already in
     /// scope, while just changing reference level or mutability.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Not much, in fact it's a very common pattern in Rust
+    /// To require that what are formally distinct variables be given distinct names.
-    /// code. Still, some may opt to avoid it in their code base, they can set this
+    ///
-    /// lint to `Warn`.
+    /// See also `shadow_reuse` and `shadow_unrelated` for other restrictions on shadowing.
     ///
     /// ### Example
     /// ```no_run
@@ -42,12 +42,13 @@ declare_clippy_lint! {
     /// Checks for bindings that shadow other bindings already in
     /// scope, while reusing the original value.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Not too much, in fact it's a common pattern in Rust
+    /// Some argue that name shadowing like this hurts readability,
-    /// code. Still, some argue that name shadowing like this hurts readability,
     /// because a value may be bound to different things depending on position in
     /// the code.
     ///
+    /// See also `shadow_same` and `shadow_unrelated` for other restrictions on shadowing.
+    ///
     /// ### Example
     /// ```no_run
     /// let x = 2;
@@ -70,11 +71,14 @@ declare_clippy_lint! {
     /// scope, either without an initialization or with one that does not even use
     /// the original value.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Name shadowing can hurt readability, especially in
+    /// Shadowing a binding with a closely related one is part of idiomatic Rust,
+    /// but shadowing a binding by accident with an unrelated one may indicate a mistake.
+    ///
+    /// Additionally, name shadowing in general can hurt readability, especially in
     /// large code bases, because it is easy to lose track of the active binding at
-    /// any place in the code. This can be alleviated by either giving more specific
+    /// any place in the code. If linting against all shadowing is desired, you may wish
-    /// names to bindings or introducing more scopes to contain the bindings.
+    /// to use the `shadow_same` and `shadow_reuse` lints as well.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/single_call_fn.rs

@@ -13,13 +13,20 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for functions that are only used once. Does not lint tests.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It's usually not, splitting a function into multiple parts often improves readability and in
+    /// If a function is only used once (perhaps because it used to be used more widely),
-    /// the case of generics, can prevent the compiler from duplicating the function dozens of
+    /// then the code could be simplified by moving that function's code into its caller.
-    /// time; instead, only duplicating a thunk. But this can prevent segmentation across a
-    /// codebase, where many small functions are used only once.
     ///
-    /// Note: If this lint is used, prepare to allow this a lot.
+    /// However, there are reasons not to do this everywhere:
+    ///
+    /// * Splitting a large function into multiple parts often improves readability
+    ///   by giving names to its parts.
+    /// * A function’s signature might serve a necessary purpose, such as constraining
+    ///   the type of a closure passed to it.
+    /// * Generic functions might call non-generic functions to reduce duplication
+    ///   in the produced machine code.
+    ///
+    /// If this lint is used, prepare to `#[allow]` it a lot.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/single_char_lifetime_names.rs

@@ -9,11 +9,10 @@ declare_clippy_lint! {
     /// Checks for lifetimes with names which are one character
     /// long.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// A single character is likely not enough to express the
     /// purpose of a lifetime. Using a longer name can make code
-    /// easier to understand, especially for those who are new to
+    /// easier to understand.
-    /// Rust.
     ///
     /// ### Known problems
     /// Rust programmers and learning resources tend to use single

clippy_lints/src/std_instead_of_core.rs

@@ -12,11 +12,9 @@ use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
     /// ### What it does
-    ///
     /// Finds items imported through `std` when available through `core`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    ///
     /// Crates which have `no_std` compatibility may wish to ensure types are imported from core to ensure
     /// disabling `std` does not cause the crate to fail to compile. This lint is also useful for crates
     /// migrating to become `no_std` compatible.
@@ -37,11 +35,9 @@ declare_clippy_lint! {
 
 declare_clippy_lint! {
     /// ### What it does
-    ///
     /// Finds items imported through `std` when available through `alloc`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    ///
     /// Crates which have `no_std` compatibility and require alloc may wish to ensure types are imported from
     /// alloc to ensure disabling `std` does not cause the crate to fail to compile. This lint is also useful
     /// for crates migrating to become `no_std` compatible.
@@ -63,11 +59,9 @@ declare_clippy_lint! {
 
 declare_clippy_lint! {
     /// ### What it does
-    ///
     /// Finds items imported through `alloc` when available through `core`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    ///
     /// Crates which have `no_std` compatibility and may optionally require alloc may wish to ensure types are
     /// imported from core to ensure disabling `alloc` does not cause the crate to fail to compile. This lint
     /// is also useful for crates migrating to become `no_std` compatible.

clippy_lints/src/strings.rs

@@ -45,10 +45,10 @@ declare_clippy_lint! {
     /// `String`, but only if [`string_add_assign`](#string_add_assign) does *not*
     /// match.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// It's not bad in and of itself. However, this particular
+    /// This particular
     /// `Add` implementation is asymmetric (the other operand need not be `String`,
-    /// but `x` does), while addition as mathematically defined is symmetric, also
+    /// but `x` does), while addition as mathematically defined is symmetric, and
     /// the `String::push_str(_)` function is a perfectly good replacement.
     /// Therefore, some dislike it and wish not to have it in their code.
     ///
@@ -123,7 +123,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for slice operations on strings
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// UTF-8 characters span multiple bytes, and it is easy to inadvertently confuse character
     /// counts and string indices. This may lead to panics, and should warrant some test cases
     /// containing wide UTF-8 characters. This lint is most useful in code that should avoid
@@ -364,10 +364,10 @@ declare_clippy_lint! {
     /// ### What it does
     /// This lint checks for `.to_string()` method calls on values of type `&str`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// The `to_string` method is also used on other types to convert them to a string.
-    /// When called on a `&str` it turns the `&str` into the owned variant `String`, which can be better
+    /// When called on a `&str` it turns the `&str` into the owned variant `String`, which can be
-    /// expressed with `.to_owned()`.
+    /// more specifically expressed with `.to_owned()`.
     ///
     /// ### Example
     /// ```no_run
@@ -415,9 +415,10 @@ declare_clippy_lint! {
     /// ### What it does
     /// This lint checks for `.to_string()` method calls on values of type `String`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// The `to_string` method is also used on other types to convert them to a string.
-    /// When called on a `String` it only clones the `String`, which can be better expressed with `.clone()`.
+    /// When called on a `String` it only clones the `String`, which can be more specifically
+    /// expressed with `.clone()`.
     ///
     /// ### Example
     /// ```no_run

clippy_lints/src/suspicious_xor_used_as_pow.rs

@@ -11,8 +11,10 @@ use rustc_session::declare_lint_pass;
 declare_clippy_lint! {
     /// ### What it does
     /// Warns for a Bitwise XOR (`^`) operator being probably confused as a powering. It will not trigger if any of the numbers are not in decimal.
-    /// ### Why is this bad?
+    ///
+    /// ### Why restrict this?
     /// It's most probably a typo and may lead to unexpected behaviours.
+    ///
     /// ### Example
     /// ```no_run
     /// let x = 3_i32 ^ 4_i32;

clippy_lints/src/tests_outside_test_module.rs

@@ -11,9 +11,11 @@ declare_clippy_lint! {
     /// ### What it does
     /// Triggers when a testing function (marked with the `#[test]` attribute) isn't inside a testing module
     /// (marked with `#[cfg(test)]`).
-    /// ### Why is this bad?
+    ///
+    /// ### Why restrict this?
     /// The idiomatic (and more performant) way of writing tests is inside a testing module (flagged with `#[cfg(test)]`),
     /// having test functions outside of this module is confusing and may lead to them being "hidden".
+    ///
     /// ### Example
     /// ```no_run
     /// #[test]

clippy_lints/src/types/mod.rs

@@ -217,7 +217,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `Rc<T>` and `Arc<T>` when `T` is a mutable buffer type such as `String` or `Vec`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Expressions such as `Rc<String>` usually have no advantage over `Rc<str>`, since
     /// it is larger and involves an extra level of indirection, and doesn't implement `Borrow<str>`.
     ///
@@ -274,7 +274,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `Rc<Mutex<T>>`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// `Rc` is used in single thread and `Mutex` is used in multi thread.
     /// Consider using `Rc<RefCell<T>>` in single thread or `Arc<Mutex<T>>` in multi thread.
     ///

clippy_lints/src/undocumented_unsafe_blocks.rs

@@ -38,10 +38,9 @@ declare_clippy_lint! {
     /// );
     /// ```
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// Undocumented unsafe blocks and impls can make it difficult to
+    /// Undocumented unsafe blocks and impls can make it difficult to read and maintain code.
-    /// read and maintain code, as well as uncover unsoundness
+    /// Writing out the safety justification may help in discovering unsoundness or bugs.
-    /// and bugs.
     ///
     /// ### Example
     /// ```no_run
@@ -67,7 +66,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for `// SAFETY: ` comments on safe code.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Safe code has no safety requirements, so there is no need to
     /// describe safety invariants.
     ///

clippy_lints/src/unicode.rs

@@ -31,7 +31,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for non-ASCII characters in string and char literals.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Yeah, we know, the 90's called and wanted their charset
     /// back. Even so, there still are editors and other programs out there that
     /// don't work well with Unicode. So if the code is meant to be used

clippy_lints/src/unnecessary_self_imports.rs

@@ -9,7 +9,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for imports ending in `::{self}`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// In most cases, this can be written much more cleanly by omitting `::{self}`.
     ///
     /// ### Known problems

clippy_lints/src/unwrap_in_result.rs

@@ -13,8 +13,10 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for functions of type `Result` that contain `expect()` or `unwrap()`
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// These functions promote recoverable errors to non-recoverable errors which may be undesirable in code bases which wish to avoid panics.
+    /// These functions promote recoverable errors to non-recoverable errors,
+    /// which may be undesirable in code bases which wish to avoid panics,
+    /// or be a bug in the specific function.
     ///
     /// ### Known problems
     /// This can cause false positives in functions that handle both recoverable and non recoverable errors.

clippy_lints/src/visibility.rs

@@ -32,7 +32,7 @@ declare_clippy_lint! {
     /// ### What it does
     /// Checks for usage of `pub(<loc>)` with `in`.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Consistency. Use it or don't, just be consistent about it.
     ///
     /// Also see the `pub_without_shorthand` lint for an alternative.
@@ -57,7 +57,7 @@ declare_clippy_lint! {
     /// Note: As you cannot write a module's path in `pub(<loc>)`, this will only trigger on
     /// `pub(super)` and the like.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// Consistency. Use it or don't, just be consistent about it.
     ///
     /// Also see the `pub_with_shorthand` lint for an alternative.

clippy_lints/src/write.rs

@@ -66,7 +66,7 @@ declare_clippy_lint! {
     /// Checks for printing on *stdout*. The purpose of this lint
     /// is to catch debugging remnants.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// People often print on *stdout* while debugging an
     /// application and might forget to remove those prints afterward.
     ///
@@ -88,7 +88,7 @@ declare_clippy_lint! {
     /// Checks for printing on *stderr*. The purpose of this lint
     /// is to catch debugging remnants.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
     /// People often print on *stderr* while debugging an
     /// application and might forget to remove those prints afterward.
     ///
@@ -110,15 +110,18 @@ declare_clippy_lint! {
     /// Checks for usage of `Debug` formatting. The purpose of this
     /// lint is to catch debugging remnants.
     ///
-    /// ### Why is this bad?
+    /// ### Why restrict this?
-    /// The purpose of the `Debug` trait is to facilitate
+    /// The purpose of the `Debug` trait is to facilitate debugging Rust code,
-    /// debugging Rust code. It should not be used in user-facing output.
+    /// and [no guarantees are made about its output][stability].
+    /// It should not be used in user-facing output.
     ///
     /// ### Example
     /// ```no_run
     /// # let foo = "bar";
     /// println!("{:?}", foo);
     /// ```
+    ///
+    /// [stability]: https://doc.rust-lang.org/stable/std/fmt/trait.Debug.html#stability
     #[clippy::version = "pre 1.29.0"]
     pub USE_DEBUG,
     restriction,