Improve lint doc consistency

Author: Serial-ATA

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,16 @@ 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 +248,20 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// fn fn1() -> i16 {
     ///     1
     /// };
-    /// let _ = fn1 as i32;
+    /// # 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,23 +283,31 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad: fn1 is cast as `usize`
+    /// // fn1 is cast as `usize`
     /// fn fn1() -> u16 {
     ///     1
     /// };
-    /// let _ = fn1 as usize;
+    /// # 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;
+    /// # let _ =
+    /// fn2() as usize;
+    ///
+    /// // or
     ///
-    /// // Good: maybe you intended to cast it to a function type?
+    /// // maybe you intended to cast it to a function type?
     /// fn fn3() -> u16 {
     ///     1
     /// }
-    /// let _ = fn3 as fn() -> u16;
+    /// # let _ =
+    /// fn3 as fn() -> u16;
     /// ```
     #[clippy::version = "1.58.0"]
     pub FN_TO_NUMERIC_CAST_ANY,

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/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