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.

Author: kpreid

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?
- /// `#[expect]` attributes suppress the lint emission, but emit a warning, if
+ /// ### Why restrict this?
+ /// `#[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?
- /// The lint has been enabled to indicate a preference
- /// for AT&T x86 assembly syntax.
+ /// ### Why restrict this?
+ /// To enforce consistent use of 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?
- /// The lint has been enabled to indicate a preference
- /// for Intel x86 assembly syntax.
+ /// ### Why restrict this?
+ /// To enforce consistent use of 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?
- /// An assertion failure cannot output an useful message of the error.
+ /// ### Why restrict this?
+ /// 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?
- /// Allowing a lint should always have a reason. This reason should be documented to
- /// ensure that others understand the reasoning
+ /// ### Why restrict this?
+ /// Justifying each `allow` helps readers 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?
- /// The conversion might include lossy conversion and dangerous cast that might go
+ /// ### Why restrict this?
+ /// 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?
- /// Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`.
+ /// ### Why restrict this?
+ /// 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