Auto merge of #8954 - Serial-ATA:doc-comment-issues, r=xFrednet

Improve lint doc consistency

changelog: none

This is a continuation of #8908.

Notable changes:
- Removed empty `Known Problems` sections
- Removed "Good"/"Bad" language (replaced with "Use instead")
- Removed (and added some 😄) duplication
- Ignored the [`create_dir`] example so it doesn't create `clippy_lints/foo` 😄

clippy_lints/src/assertions_on_constants.rs

@@ -14,9 +14,6 @@ declare_clippy_lint! {
     /// Will be optimized out by the compiler or should probably be replaced by a
     /// `panic!()` or `unreachable!()`
     ///
-    /// ### Known problems
-    /// None
-    ///
     /// ### Example
     /// ```rust,ignore
     /// assert!(false)

clippy_lints/src/async_yields_async.rs

@@ -24,6 +24,7 @@ declare_clippy_lint! {
     ///   };
     /// }
     /// ```
+    ///
     /// Use instead:
     /// ```rust
     /// async fn foo() {}

clippy_lints/src/await_holding_invalid.rs

@@ -140,8 +140,6 @@ declare_clippy_lint! {
     /// from a memory access perspective but will cause bugs at runtime if they
     /// are held in such a way.
     ///
-    /// ### Known problems
-    ///
     /// ### Example
     ///
     /// ```toml

clippy_lints/src/bool_assert_comparison.rs

@@ -17,11 +17,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// assert_eq!("a".is_empty(), false);
     /// assert_ne!("a".is_empty(), true);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// assert!(!"a".is_empty());
     /// ```
     #[clippy::version = "1.53.0"]

clippy_lints/src/borrow_deref_ref.rs

@@ -18,7 +18,7 @@ declare_clippy_lint! {
     /// Dereferencing and then borrowing a reference value has no effect in most cases.
     ///
     /// ### Known problems
-    /// false negative on such code:
+    /// False negative on such code:
     /// ```
     /// let x = &12;
     /// let addr_x = &x as *const _ as usize;
@@ -29,17 +29,20 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
+    /// fn foo(_x: &str) {}
+    ///
     /// let s = &String::new();
     ///
-    /// // Bad
     /// let a: &String = &* s;
     /// foo(&*s);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # fn foo(_x: &str) {}
+    /// # let s = &String::new();
     /// let a: &String = s;
     /// foo(&**s);
-    ///
-    /// fn foo(_: &str){ }
     /// ```
     #[clippy::version = "1.59.0"]
     pub BORROW_DEREF_REF,

clippy_lints/src/casts/mod.rs

@@ -219,13 +219,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// fn fun() -> i32 { 1 }
-    /// let a = fun as i64;
+    /// let _ = fun as i64;
+    /// ```
     ///
-    /// // Good
-    /// fn fun2() -> i32 { 1 }
-    /// let a = fun2 as usize;
+    /// Use instead:
+    /// ```rust
+    /// # fn fun() -> i32 { 1 }
+    /// let _ = fun as usize;
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub FN_TO_NUMERIC_CAST,
@@ -245,17 +246,19 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// fn fn1() -> i16 {
     ///     1
     /// };
     /// let _ = fn1 as i32;
+    /// ```
     ///
-    /// // Better: Cast to usize first, then comment with the reason for the truncation
-    /// fn fn2() -> i16 {
+    /// Use instead:
+    /// ```rust
+    /// // Cast to usize first, then comment with the reason for the truncation
+    /// fn fn1() -> i16 {
     ///     1
     /// };
-    /// let fn_ptr = fn2 as usize;
+    /// let fn_ptr = fn1 as usize;
     /// let fn_ptr_truncated = fn_ptr as i32;
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -277,19 +280,24 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad: fn1 is cast as `usize`
+    /// // fn1 is cast as `usize`
     /// fn fn1() -> u16 {
     ///     1
     /// };
     /// let _ = fn1 as usize;
+    /// ```
     ///
-    /// // Good: maybe you intended to call the function?
+    /// Use instead:
+    /// ```rust
+    /// // maybe you intended to call the function?
     /// fn fn2() -> u16 {
     ///     1
     /// };
     /// let _ = fn2() as usize;
     ///
-    /// // Good: maybe you intended to cast it to a function type?
+    /// // or
+    ///
+    /// // maybe you intended to cast it to a function type?
     /// fn fn3() -> u16 {
     ///     1
     /// }

clippy_lints/src/checked_conversions.rs

@@ -22,18 +22,14 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let foo: u32 = 5;
-    /// # let _ =
-    /// foo <= i32::MAX as u32
-    /// # ;
+    /// foo <= i32::MAX as u32;
     /// ```
     ///
-    /// Could be written:
-    ///
+    /// Use instead:
     /// ```rust
     /// # let foo = 1;
-    /// # let _ =
-    /// i32::try_from(foo).is_ok()
-    /// # ;
+    /// # #[allow(unused)]
+    /// i32::try_from(foo).is_ok();
     /// ```
     #[clippy::version = "1.37.0"]
     pub CHECKED_CONVERSIONS,

clippy_lints/src/comparison_chain.rs

@@ -35,7 +35,6 @@ declare_clippy_lint! {
     /// ```
     ///
     /// Use instead:
-    ///
     /// ```rust,ignore
     /// use std::cmp::Ordering;
     /// # fn a() {}

clippy_lints/src/create_dir.rs

@@ -15,12 +15,12 @@ declare_clippy_lint! {
     /// Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`.
     ///
     /// ### Example
-    ///
-    /// ```rust
+    /// ```rust,ignore
     /// std::fs::create_dir("foo");
     /// ```
+    ///
     /// Use instead:
-    /// ```rust
+    /// ```rust,ignore
     /// std::fs::create_dir_all("foo");
     /// ```
     #[clippy::version = "1.48.0"]

clippy_lints/src/dbg_macro.rs

@@ -18,10 +18,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// dbg!(true)
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust,ignore
     /// true
     /// ```
     #[clippy::version = "1.34.0"]

clippy_lints/src/default.rs

@@ -18,15 +18,16 @@ declare_clippy_lint! {
     /// Checks for literal calls to `Default::default()`.
     ///
     /// ### Why is this bad?
-    /// It's more clear to the reader to use the name of the type whose default is
-    /// being gotten than the generic `Default`.
+    /// It's easier for the reader if the name of the type is used, rather than the
+    /// generic `Default`.
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let s: String = Default::default();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let s = String::default();
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -47,13 +48,13 @@ declare_clippy_lint! {
     /// Assignments to patterns that are of tuple type are not linted.
     ///
     /// ### Example
-    /// Bad:
     /// ```
     /// # #[derive(Default)]
     /// # struct A { i: i32 }
     /// let mut a: A = Default::default();
     /// a.i = 42;
     /// ```
+    ///
     /// Use instead:
     /// ```
     /// # #[derive(Default)]

clippy_lints/src/dereference.rs

@@ -30,13 +30,14 @@ declare_clippy_lint! {
     /// let a: &mut String = &mut String::from("foo");
     /// let b: &str = a.deref();
     /// ```
-    /// Could be written as:
+    ///
+    /// Use instead:
     /// ```rust
     /// let a: &mut String = &mut String::from("foo");
     /// let b = &*a;
     /// ```
     ///
-    /// This lint excludes
+    /// This lint excludes:
     /// ```rust,ignore
     /// let _ = d.unwrap().deref();
     /// ```
@@ -59,11 +60,13 @@ declare_clippy_lint! {
     /// ```rust
     /// fn fun(_a: &i32) {}
     ///
-    /// // Bad
     /// let x: &i32 = &&&&&&5;
     /// fun(&x);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # fn fun(_a: &i32) {}
     /// let x: &i32 = &5;
     /// fun(x);
     /// ```
@@ -82,13 +85,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let x = Some("");
     /// if let Some(ref x) = x {
     ///     // use `x` here
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let x = Some("");
     /// if let Some(x) = x {
     ///     // use `&x` here

clippy_lints/src/derivable_impls.rs

@@ -30,8 +30,7 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
-    /// Could be written as:
-    ///
+    /// Use instead:
     /// ```rust
     /// #[derive(Default)]
     /// struct Foo {
@@ -45,7 +44,6 @@ declare_clippy_lint! {
     /// specialized than what derive will produce. This lint can't detect the manual `impl`
     /// has exactly equal bounds, and therefore this lint is disabled for types with
     /// generic parameters.
-    ///
     #[clippy::version = "1.57.0"]
     pub DERIVABLE_IMPLS,
     complexity,

clippy_lints/src/enum_variants.rs

@@ -60,7 +60,8 @@ declare_clippy_lint! {
     ///     struct BlackForestCake;
     /// }
     /// ```
-    /// Could be written as:
+    ///
+    /// Use instead:
     /// ```rust
     /// mod cake {
     ///     struct BlackForest;

clippy_lints/src/eq_op.rs

@@ -52,15 +52,13 @@ declare_clippy_lint! {
     /// ### Why is this bad?
     /// It is more idiomatic to dereference the other argument.
     ///
-    /// ### Known problems
-    /// None
-    ///
     /// ### Example
-    /// ```ignore
-    /// // Bad
+    /// ```rust,ignore
     /// &x == y
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust,ignore
     /// x == *y
     /// ```
     #[clippy::version = "pre 1.29.0"]

clippy_lints/src/eta_reduction.rs

@@ -34,14 +34,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// xs.map(|x| foo(x))
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust,ignore
+    /// // where `foo(_)` is a plain function that takes the exact argument type of `x`.
     /// xs.map(foo)
     /// ```
-    /// where `foo(_)` is a plain function that takes the exact argument type of
-    /// `x`.
     #[clippy::version = "pre 1.29.0"]
     pub REDUNDANT_CLOSURE,
     style,

clippy_lints/src/excessive_bools.rs

@@ -54,12 +54,11 @@ declare_clippy_lint! {
     /// API easier to use.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// fn f(is_round: bool, is_hot: bool) { ... }
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// enum Shape {
     ///     Round,

clippy_lints/src/float_literal.rs

@@ -45,10 +45,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let _: f32 = 16_777_217.0; // 16_777_216.0
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let _: f32 = 16_777_216.0;
     /// let _: f64 = 16_777_217.0;
     /// ```