Improve lint doc consistency

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
+    /// Use instead:
-    /// fn fun2() -> i32 { 1 }
+    /// ```rust
-    /// let a = fun2 as usize;
+    /// # 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
+    /// Use instead:
-    /// fn fn2() -> i16 {
+    /// ```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;
     ///
-    /// // 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
     /// }
-    /// 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
+    /// It's easier for the reader if the name of the type is used, rather than the
-    /// being gotten than the generic `Default`.
+    /// 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
+    /// ```rust,ignore
-    /// // Bad
     /// &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;
     /// ```

clippy_lints/src/functions/mod.rs

@@ -76,12 +76,13 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// pub fn foo(x: *const u8) {
     ///     println!("{}", unsafe { *x });
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust,ignore
     /// pub unsafe fn foo(x: *const u8) {
     ///     println!("{}", unsafe { *x });
     /// }

clippy_lints/src/get_first.rs

@@ -20,13 +20,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let x = vec![2, 3, 5];
     /// let first_element = x.get(0);
     /// ```
+    ///
     /// Use instead:
     /// ```rust
-    /// // Good
     /// let x = vec![2, 3, 5];
     /// let first_element = x.first();
     /// ```

clippy_lints/src/implicit_saturating_sub.rs

@@ -16,17 +16,15 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// let end: u32 = 10;
+    /// # let mut i: u32 = 0;
-    /// let start: u32 = 5;
-    ///
-    /// let mut i: u32 = end - start;
-    ///
-    /// // Bad
     /// if i != 0 {
     ///     i -= 1;
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let mut i: u32 = 0;
     /// i = i.saturating_sub(1);
     /// ```
     #[clippy::version = "1.44.0"]
@@ -48,7 +46,7 @@ impl<'tcx> LateLintPass<'tcx> for ImplicitSaturatingSub {
             // Check if the conditional expression is a binary operation
             if let ExprKind::Binary(ref cond_op, cond_left, cond_right) = cond.kind;
 
-            // Ensure that the binary operator is >, != and <
+            // Ensure that the binary operator is >, !=, or <
             if BinOpKind::Ne == cond_op.node || BinOpKind::Gt == cond_op.node || BinOpKind::Lt == cond_op.node;
 
             // Check if assign operation is done

clippy_lints/src/indexing_slicing.rs

@@ -17,19 +17,20 @@ declare_clippy_lint! {
     /// ### Why is this bad?
     /// This will always panic at runtime.
     ///
-    /// ### Known problems
-    /// Hopefully none.
-    ///
     /// ### Example
-    /// ```no_run
+    /// ```rust,no_run
     /// # #![allow(const_err)]
     /// let x = [1, 2, 3, 4];
     ///
-    /// // Bad
     /// x[9];
     /// &x[2..9];
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// # let x = [1, 2, 3, 4];
+    /// // Index within bounds
     ///
-    /// // Good
     /// x[0];
     /// x[3];
     /// ```
@@ -49,42 +50,34 @@ declare_clippy_lint! {
     /// Indexing and slicing can panic at runtime and there are
     /// safe alternatives.
     ///
-    /// ### Known problems
-    /// Hopefully none.
-    ///
     /// ### Example
     /// ```rust,no_run
     /// // Vector
     /// let x = vec![0; 5];
     ///
-    /// // Bad
     /// x[2];
     /// &x[2..100];
-    /// &x[2..];
-    /// &x[..100];
-    ///
-    /// // Good
-    /// x.get(2);
-    /// x.get(2..100);
-    /// x.get(2..);
-    /// x.get(..100);
     ///
     /// // Array
     /// let y = [0, 1, 2, 3];
     ///
-    /// // Bad
     /// &y[10..100];
     /// &y[10..];
-    /// &y[..100];
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// &y[2..];
+    /// ```rust
-    /// &y[..2];
+    /// # let x = vec![0; 5];
-    /// &y[0..3];
+    /// # let y = [0, 1, 2, 3];
+    /// # let _ =
+    /// x.get(2);
+    /// # let _ =
+    /// x.get(2..100);
+    ///
+    /// # let _ =
     /// y.get(10);
+    /// # let _ =
     /// y.get(10..100);
-    /// y.get(10..);
-    /// y.get(..100);
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub INDEXING_SLICING,

clippy_lints/src/infinite_iter.rs

@@ -41,6 +41,7 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// let infinite_iter = 0..;
+    /// # let _ =
     /// [0..].iter().zip(infinite_iter.take_while(|x| *x > 5));
     /// ```
     #[clippy::version = "pre 1.29.0"]

clippy_lints/src/inherent_to_string.rs

@@ -14,12 +14,8 @@ declare_clippy_lint! {
     /// ### Why is this bad?
     /// This method is also implicitly defined if a type implements the `Display` trait. As the functionality of `Display` is much more versatile, it should be preferred.
     ///
-    /// ### Known problems
-    /// None
-    ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// pub struct A;
     ///
     /// impl A {
@@ -29,8 +25,8 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
+    /// Use instead:
     /// ```rust
-    /// // Good
     /// use std::fmt;
     ///
     /// pub struct A;
@@ -54,12 +50,8 @@ declare_clippy_lint! {
     /// ### Why is this bad?
     /// This method is also implicitly defined if a type implements the `Display` trait. The less versatile inherent method will then shadow the implementation introduced by `Display`.
     ///
-    /// ### Known problems
-    /// None
-    ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// use std::fmt;
     ///
     /// pub struct A;
@@ -77,8 +69,8 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
+    /// Use instead:
     /// ```rust
-    /// // Good
     /// use std::fmt;
     ///
     /// pub struct A;

clippy_lints/src/int_plus_one.rs

@@ -21,8 +21,7 @@ declare_clippy_lint! {
     /// if x >= y + 1 {}
     /// ```
     ///
-    /// Could be written as:
+    /// Use instead:
-    ///
     /// ```rust
     /// # let x = 1;
     /// # let y = 1;

clippy_lints/src/integer_division.rs

@@ -15,11 +15,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let x = 3 / 2;
     /// println!("{}", x);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let x = 3f32 / 2f32;
     /// println!("{}", x);
     /// ```

clippy_lints/src/items_after_statements.rs

@@ -17,7 +17,6 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// fn foo() {
     ///     println!("cake");
     /// }
@@ -31,8 +30,8 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
+    /// Use instead:
     /// ```rust
-    /// // Good
     /// fn foo() {
     ///     println!("cake");
     /// }

clippy_lints/src/large_const_arrays.rs

@@ -21,10 +21,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// pub const a = [0u32; 1_000_000];
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust.ignore
     /// pub static a = [0u32; 1_000_000];
     /// ```
     #[clippy::version = "1.44.0"]

clippy_lints/src/large_enum_variant.rs

@@ -38,12 +38,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// enum Test {
     ///     A(i32),
     ///     B([i32; 8000]),
     /// }
+    /// ```
     ///
+    /// Use instead:
+    /// ```rust
     /// // Possibly better
     /// enum Test2 {
     ///     A(i32),

clippy_lints/src/let_underscore.rs

@@ -45,13 +45,11 @@ declare_clippy_lint! {
     /// `std::mem::drop` conveys your intention better and is less error-prone.
     ///
     /// ### Example
-    ///
-    /// Bad:
     /// ```rust,ignore
     /// let _ = mutex.lock();
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// let _lock = mutex.lock();
     /// ```
@@ -75,24 +73,20 @@ declare_clippy_lint! {
     /// better and is less error-prone.
     ///
     /// ### Example
-    ///
+    /// ```rust
-    /// Bad:
+    /// # struct DroppableItem;
-    /// ```rust,ignore
-    /// struct Droppable;
-    /// impl Drop for Droppable {
-    ///     fn drop(&mut self) {}
-    /// }
     /// {
-    ///     let _ = Droppable;
+    ///     let _ = DroppableItem;
-    ///     //               ^ dropped here
+    ///     //                   ^ dropped here
     ///     /* more code */
     /// }
     /// ```
     ///
-    /// Good:
+    /// Use instead:
-    /// ```rust,ignore
+    /// ```rust
+    /// # struct DroppableItem;
     /// {
-    ///     let _droppable = Droppable;
+    ///     let _droppable = DroppableItem;
     ///     /* more code */
     ///     // dropped at end of scope
     /// }

clippy_lints/src/lib.rs

@@ -88,10 +88,11 @@ use rustc_session::Session;
 ///     ///
 ///     /// ### Example
 ///     /// ```rust
-///     /// // Bad
 ///     /// Insert a short example of code that triggers the lint
+///     /// ```
 ///     ///
-///     /// // Good
+///     /// Use instead:
+///     /// ```rust
 ///     /// Insert a short example of improved code that doesn't trigger the lint
 ///     /// ```
 ///     pub LINT_NAME,

clippy_lints/src/lifetimes.rs

@@ -36,12 +36,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad: unnecessary lifetime annotations
+    /// // Unnecessary lifetime annotations
     /// fn in_and_out<'a>(x: &'a u8, y: u8) -> &'a u8 {
     ///     x
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// fn elided(x: &u8, y: u8) -> &u8 {
     ///     x
     /// }
@@ -65,12 +67,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad: unnecessary lifetimes
+    /// // unnecessary lifetimes
     /// fn unused_lifetime<'a>(x: u8) {
     ///     // ..
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// fn no_lifetime(x: u8) {
     ///     // ...
     /// }

clippy_lints/src/literal_representation.rs

@@ -22,11 +22,16 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let _: u64 =
-    /// let x: u64 = 61864918973511;
+    /// 61864918973511
+    /// # ;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let x: u64 = 61_864_918_973_511;
+    /// ```rust
+    /// # let _: u64 =
+    /// 61_864_918_973_511
+    /// # ;
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub UNREADABLE_LITERAL,
@@ -66,11 +71,16 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let _: u64 =
-    /// let x: u64 = 618_64_9189_73_511;
+    /// 618_64_9189_73_511
+    /// # ;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let x: u64 = 61_864_918_973_511;
+    /// ```rust
+    /// # let _: u64 =
+    /// 61_864_918_973_511
+    /// # ;
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub INCONSISTENT_DIGIT_GROUPING,
@@ -125,9 +135,11 @@ declare_clippy_lint! {
     /// readable than a decimal representation.
     ///
     /// ### Example
+    /// ```text
     /// `255` => `0xFF`
     /// `65_535` => `0xFFFF`
     /// `4_042_322_160` => `0xF0F0_F0F0`
+    /// ```
     #[clippy::version = "pre 1.29.0"]
     pub DECIMAL_LITERAL_REPRESENTATION,
     restriction,

clippy_lints/src/loops/mod.rs

@@ -42,7 +42,8 @@ declare_clippy_lint! {
     ///     dst[i + 64] = src[i];
     /// }
     /// ```
-    /// Could be written as:
+    ///
+    /// Use instead:
     /// ```rust
     /// # let src = vec![1];
     /// # let mut dst = vec![0; 65];
@@ -70,7 +71,8 @@ declare_clippy_lint! {
     ///     println!("{}", vec[i]);
     /// }
     /// ```
-    /// Could be written as:
+    ///
+    /// Use instead:
     /// ```rust
     /// let vec = vec!['a', 'b', 'c'];
     /// for i in vec {
@@ -103,7 +105,8 @@ declare_clippy_lint! {
     ///     // ..
     /// }
     /// ```
-    /// can be rewritten to
+    ///
+    /// Use instead:
     /// ```rust
     /// # let y = vec![1];
     /// for x in &y {
@@ -286,7 +289,8 @@ declare_clippy_lint! {
     ///     i += 1;
     /// }
     /// ```
-    /// Could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// # let v = vec![1];
     /// # fn bar(bar: usize, baz: usize) {}
@@ -473,7 +477,7 @@ declare_clippy_lint! {
     ///
     /// ### Why is this bad?
     /// This kind of operation can be expressed more succinctly with
-    /// `vec![item;SIZE]` or `vec.resize(NEW_SIZE, item)` and using these alternatives may also
+    /// `vec![item; SIZE]` or `vec.resize(NEW_SIZE, item)` and using these alternatives may also
     /// have better performance.
     ///
     /// ### Example
@@ -488,7 +492,8 @@ declare_clippy_lint! {
     ///     vec.push(item2);
     /// }
     /// ```
-    /// could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// let item1 = 2;
     /// let item2 = 3;
@@ -516,7 +521,8 @@ declare_clippy_lint! {
     ///     println!("{}", item);
     /// }
     /// ```
-    /// could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// let item1 = 2;
     /// let item = &item1;

clippy_lints/src/matches/mod.rs

@@ -43,13 +43,16 @@ declare_clippy_lint! {
     /// ```rust
     /// # fn bar(stool: &str) {}
     /// # let x = Some("abc");
-    /// // Bad
     /// match x {
     ///     Some(ref foo) => bar(foo),
     ///     _ => (),
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # fn bar(stool: &str) {}
+    /// # let x = Some("abc");
     /// if let Some(ref foo) = x {
     ///     bar(foo);
     /// }
@@ -114,14 +117,15 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// match x {
     ///     &A(ref y) => foo(y),
     ///     &B => bar(),
     ///     _ => frob(&x),
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust,ignore
     /// match *x {
     ///     A(ref y) => foo(y),
     ///     B => bar(),
@@ -227,13 +231,16 @@ declare_clippy_lint! {
     /// ```rust
     /// let x: Option<()> = None;
     ///
-    /// // Bad
     /// let r: Option<&()> = match x {
     ///     None => None,
     ///     Some(ref v) => Some(v),
     /// };
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// let x: Option<()> = None;
     ///
-    /// // Good
     /// let r: Option<&()> = x.as_ref();
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -257,13 +264,16 @@ declare_clippy_lint! {
     /// ```rust
     /// # enum Foo { A(usize), B(usize) }
     /// # let x = Foo::B(1);
-    /// // Bad
     /// match x {
     ///     Foo::A(_) => {},
     ///     _ => {},
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # enum Foo { A(usize), B(usize) }
+    /// # let x = Foo::B(1);
     /// match x {
     ///     Foo::A(_) => {},
     ///     Foo::B(_) => {},
@@ -290,14 +300,17 @@ declare_clippy_lint! {
     /// ```rust
     /// # enum Foo { A, B, C }
     /// # let x = Foo::B;
-    /// // Bad
     /// match x {
     ///     Foo::A => {},
     ///     Foo::B => {},
     ///     _ => {},
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # enum Foo { A, B, C }
+    /// # let x = Foo::B;
     /// match x {
     ///     Foo::A => {},
     ///     Foo::B => {},
@@ -320,14 +333,17 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let s = "foo";
-    /// match "foo" {
+    /// match s {
     ///     "a" => {},
     ///     "bar" | _ => {},
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// match "foo" {
+    /// ```rust
+    /// # let s = "foo";
+    /// match s {
     ///     "a" => {},
     ///     _ => {},
     /// }
@@ -389,15 +405,17 @@ declare_clippy_lint! {
     /// ```rust
     /// # let a = 1;
     /// # let b = 2;
-    ///
-    /// // Bad
     /// match (a, b) {
     ///     (c, d) => {
     ///         // useless match
     ///     }
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let a = 1;
+    /// # let b = 2;
     /// let (c, d) = (a, b);
     /// ```
     #[clippy::version = "1.43.0"]
@@ -419,13 +437,16 @@ declare_clippy_lint! {
     /// # struct A { a: i32 }
     /// let a = A { a: 5 };
     ///
-    /// // Bad
     /// match a {
     ///     A { a: 5, .. } => {},
     ///     _ => {},
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # struct A { a: i32 }
+    /// # let a = A { a: 5 };
     /// match a {
     ///     A { a: 5 } => {},
     ///     _ => {},
@@ -509,7 +530,6 @@ declare_clippy_lint! {
     /// ```rust
     /// let x = Some(5);
     ///
-    /// // Bad
     /// let a = match x {
     ///     Some(0) => true,
     ///     _ => false,
@@ -520,8 +540,11 @@ declare_clippy_lint! {
     /// } else {
     ///     false
     /// };
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// let x = Some(5);
     /// let a = matches!(x, Some(0));
     /// ```
     #[clippy::version = "1.47.0"]
@@ -695,19 +718,18 @@ declare_clippy_lint! {
     /// let arr = vec![0, 1, 2, 3];
     /// let idx = 1;
     ///
-    /// // Bad
     /// match arr[idx] {
     ///     0 => println!("{}", 0),
     ///     1 => println!("{}", 3),
     ///     _ => {},
     /// }
     /// ```
+    ///
     /// Use instead:
     /// ```rust, no_run
     /// let arr = vec![0, 1, 2, 3];
     /// let idx = 1;
     ///
-    /// // Good
     /// match arr.get(idx) {
     ///     Some(0) => println!("{}", 0),
     ///     Some(1) => println!("{}", 3),

clippy_lints/src/methods/mod.rs

@@ -124,27 +124,27 @@ declare_clippy_lint! {
     /// It's often inefficient to clone all elements of an iterator, when eventually, only some
     /// of them will be consumed.
     ///
-    /// ### Examples
-    /// ```rust
-    /// # let vec = vec!["string".to_string()];
-    ///
-    /// // Bad
-    /// vec.iter().cloned().take(10);
-    ///
-    /// // Good
-    /// vec.iter().take(10).cloned();
-    ///
-    /// // Bad
-    /// vec.iter().cloned().last();
-    ///
-    /// // Good
-    /// vec.iter().last().cloned();
-    ///
-    /// ```
     /// ### Known Problems
     /// This `lint` removes the side of effect of cloning items in the iterator.
     /// A code that relies on that side-effect could fail.
     ///
+    /// ### Examples
+    /// ```rust
+    /// # let vec = vec!["string".to_string()];
+    /// # let _ =
+    /// vec.iter().cloned().take(10);
+    /// # let _ =
+    /// vec.iter().cloned().last();
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// # let vec = vec!["string".to_string()];
+    /// # let _ =
+    /// vec.iter().take(10).cloned();
+    /// # let _ =
+    /// vec.iter().last().cloned();
+    /// ```
     #[clippy::version = "1.59.0"]
     pub ITER_OVEREAGER_CLONED,
     perf,
@@ -342,11 +342,12 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let x = Ok::<_, ()>(());
-    ///
-    /// // Bad
     /// x.ok().expect("why did I do this again?");
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let x = Ok::<_, ()>(());
     /// x.expect("why did I do this again?");
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -390,12 +391,13 @@ declare_clippy_lint! {
     /// ### Examples
     /// ```rust
     /// # let x = Some(1);
-    ///
-    /// // Bad
     /// x.unwrap_or_else(Default::default);
     /// x.unwrap_or_else(u32::default);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let x = Some(1);
     /// x.unwrap_or_default();
     /// ```
     #[clippy::version = "1.56.0"]
@@ -453,11 +455,12 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let opt = Some(1);
-    ///
-    /// // Bad
     /// opt.map_or(None, |a| Some(a + 1));
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let opt = Some(1);
     /// opt.and_then(|a| Some(a + 1));
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -475,13 +478,12 @@ declare_clippy_lint! {
     /// `_.ok()`.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// # let r: Result<u32, &str> = Ok(1);
     /// assert_eq!(Some(1), r.map_or(None, Some));
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// # let r: Result<u32, &str> = Ok(1);
     /// assert_eq!(Some(1), r.ok());
@@ -538,7 +540,8 @@ declare_clippy_lint! {
     /// # let vec = vec![1];
     /// vec.iter().filter(|x| **x == 0).next();
     /// ```
-    /// Could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// # let vec = vec![1];
     /// vec.iter().find(|x| **x == 0);
@@ -562,7 +565,8 @@ declare_clippy_lint! {
     /// # let vec = vec![1];
     /// vec.iter().skip_while(|x| **x == 0).next();
     /// ```
-    /// Could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// # let vec = vec![1];
     /// vec.iter().find(|x| **x != 0);
@@ -586,11 +590,16 @@ declare_clippy_lint! {
     /// let vec = vec![vec![1]];
     /// let opt = Some(5);
     ///
-    /// // Bad
+    /// # let _ =
     /// vec.iter().map(|x| x.iter()).flatten();
     /// opt.map(|x| Some(x * 2)).flatten();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let vec = vec![vec![1]];
+    /// # let opt = Some(5);
+    /// # let _ =
     /// vec.iter().flat_map(|x| x.iter());
     /// opt.and_then(|x| Some(x * 2));
     /// ```
@@ -610,15 +619,16 @@ declare_clippy_lint! {
     /// less performant.
     ///
      /// ### Example
-    /// Bad:
     /// ```rust
+    /// # let  _ =
     /// (0_i32..10)
     ///     .filter(|n| n.checked_add(1).is_some())
     ///     .map(|n| n.checked_add(1).unwrap());
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
+    /// # let _ =
     /// (0_i32..10).filter_map(|n| n.checked_add(1));
     /// ```
     #[clippy::version = "1.51.0"]
@@ -637,14 +647,13 @@ declare_clippy_lint! {
     /// less performant.
     ///
      /// ### Example
-    /// Bad:
     /// ```rust
     /// (0_i32..10)
     ///     .find(|n| n.checked_add(1).is_some())
     ///     .map(|n| n.checked_add(1).unwrap());
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// (0_i32..10).find_map(|n| n.checked_add(1));
     /// ```
@@ -713,16 +722,20 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// let vec = vec![1];
+    /// # let _ =
     /// vec.iter().find(|x| **x == 0).is_some();
     ///
-    /// let _ = "hello world".find("world").is_none();
+    /// # let _ =
+    /// "hello world".find("world").is_none();
     /// ```
-    /// Could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// let vec = vec![1];
     /// vec.iter().any(|x| *x == 0);
     ///
-    /// let _ = !"hello world".contains("world");
+    /// # let _ =
+    /// !"hello world".contains("world");
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub SEARCH_IS_SOME,
@@ -744,7 +757,8 @@ declare_clippy_lint! {
     /// let name = "foo";
     /// if name.chars().next() == Some('_') {};
     /// ```
-    /// Could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// let name = "foo";
     /// if name.starts_with('_') {};
@@ -899,10 +913,13 @@ declare_clippy_lint! {
     /// # use std::rc::Rc;
     /// let x = Rc::new(1);
     ///
-    /// // Bad
     /// x.clone();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # use std::rc::Rc;
+    /// # let x = Rc::new(1);
     /// Rc::clone(&x);
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -1034,11 +1051,13 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// _.split("x");
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust,ignore
     /// _.split('x');
+    /// ```
     #[clippy::version = "pre 1.29.0"]
     pub SINGLE_CHAR_PATTERN,
     perf,
@@ -1099,12 +1118,14 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # use std::collections::HashSet;
-    /// // Bad
     /// # let mut s = HashSet::new();
     /// # s.insert(1);
     /// let x = s.iter().nth(0);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # use std::collections::HashSet;
     /// # let mut s = HashSet::new();
     /// # s.insert(1);
     /// let x = s.iter().next();
@@ -1210,11 +1231,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let x = vec![2, 3, 5];
     /// let last_element = x.get(x.len() - 1);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let x = vec![2, 3, 5];
     /// let last_element = x.last();
     /// ```
@@ -1273,10 +1295,14 @@ declare_clippy_lint! {
     /// let mut a = vec![1, 2, 3];
     /// let mut b = vec![4, 5, 6];
     ///
-    /// // Bad
     /// a.extend(b.drain(..));
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// let mut a = vec![1, 2, 3];
+    /// let mut b = vec![4, 5, 6];
     ///
-    /// // Good
     /// a.append(&mut b);
     /// ```
     #[clippy::version = "1.55.0"]
@@ -1351,11 +1377,12 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let name = "_";
-    ///
-    /// // Bad
     /// name.chars().last() == Some('_') || name.chars().next_back() == Some('-');
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let name = "_";
     /// name.ends_with('_') || name.ends_with('-');
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -1401,11 +1428,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// let _ = (0..3).fold(false, |acc, x| acc || x > 2);
+    /// # let _ =
+    /// (0..3).fold(false, |acc, x| acc || x > 2);
     /// ```
-    /// This could be written as:
+    ///
+    /// Use instead:
     /// ```rust
-    /// let _ = (0..3).any(|x| x > 2);
+    /// # let _ =
+    /// (0..3).any(|x| x > 2);
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub UNNECESSARY_FOLD,
@@ -1485,11 +1515,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let _ =
-    /// let _ = (&vec![3, 4, 5]).into_iter();
+    /// (&vec![3, 4, 5]).into_iter();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let _ = (&vec![3, 4, 5]).iter();
+    /// ```rust
+    /// # let _ =
+    /// (&vec![3, 4, 5]).iter();
     /// ```
     #[clippy::version = "1.32.0"]
     pub INTO_ITER_ON_REF,
@@ -1704,13 +1737,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// let mut string = String::new();
+    /// # let mut string = String::new();
     /// string.insert_str(0, "R");
     /// string.push_str("R");
     /// ```
-    /// Could be written as
+    ///
+    /// Use instead:
     /// ```rust
-    /// let mut string = String::new();
+    /// # let mut string = String::new();
     /// string.insert(0, 'R');
     /// string.push('R');
     /// ```
@@ -1897,11 +1931,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let _ =
-    /// let _ = "Hello".bytes().nth(3);
+    /// "Hello".bytes().nth(3);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let _ = "Hello".as_bytes().get(3);
+    /// ```rust
+    /// # let _ =
+    /// "Hello".as_bytes().get(3);
     /// ```
     #[clippy::version = "1.52.0"]
     pub BYTES_NTH,
@@ -1945,15 +1982,20 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let some_vec = vec![0, 1, 2, 3];
-    /// let _ = some_vec.iter().count();
+    /// # let _ =
-    /// let _ = &some_vec[..].iter().count();
+    /// some_vec.iter().count();
+    /// # let _ =
+    /// &some_vec[..].iter().count();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let some_vec = vec![0, 1, 2, 3];
-    /// let _ = some_vec.len();
+    /// # let _ =
-    /// let _ = &some_vec[..].len();
+    /// some_vec.len();
+    /// # let _ =
+    /// &some_vec[..].len();
     /// ```
     #[clippy::version = "1.52.0"]
     pub ITER_COUNT,
@@ -1973,16 +2015,17 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let s = "";
-    /// let s = "";
     /// for x in s.splitn(1, ":") {
-    ///     // use x
+    ///     // ..
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let s = "";
+    /// ```rust
+    /// # let s = "";
     /// for x in s.splitn(2, ":") {
-    ///     // use x
+    ///     // ..
     /// }
     /// ```
     #[clippy::version = "1.54.0"]
@@ -2000,10 +2043,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let x: String = std::iter::repeat('x').take(10).collect();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let x: String = "x".repeat(10);
     /// ```
     #[clippy::version = "1.54.0"]
@@ -2021,7 +2065,6 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// let s = "key=value=add";
     /// let (key, value) = s.splitn(2, '=').next_tuple()?;
     /// let value = s.splitn(2, '=').nth(1)?;
@@ -2030,9 +2073,9 @@ declare_clippy_lint! {
     /// let key = parts.next()?;
     /// let value = parts.next()?;
     /// ```
+    ///
     /// Use instead:
     /// ```rust,ignore
-    /// // Good
     /// let s = "key=value=add";
     /// let (key, value) = s.split_once('=')?;
     /// let value = s.split_once('=')?.1;
@@ -2057,13 +2100,12 @@ declare_clippy_lint! {
     /// that both functions return a lazy iterator.
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let str = "key=value=add";
     /// let _ = str.splitn(3, '=').next().unwrap();
     /// ```
+    ///
     /// Use instead:
     /// ```rust
-    /// // Good
     /// let str = "key=value=add";
     /// let _ = str.split('=').next().unwrap();
     /// ```
@@ -2149,7 +2191,8 @@ declare_clippy_lint! {
     /// let a = Some(&1);
     /// let b = a.as_deref(); // goes from Option<&i32> to Option<&i32>
     /// ```
-    /// Could be written as:
+    ///
+    /// Use instead:
     /// ```rust
     /// let a = Some(&1);
     /// let b = a;

clippy_lints/src/misc.rs

@@ -45,16 +45,13 @@ declare_clippy_lint! {
     /// dereferences, e.g., changing `*x` to `x` within the function.
     ///
     /// ### Example
-    /// ```rust,ignore
+    /// ```rust
-    /// // Bad
+    /// fn foo(ref _x: u8) {}
-    /// fn foo(ref x: u8) -> bool {
+    /// ```
-    ///     true
-    /// }
     ///
-    /// // Good
+    /// Use instead:
-    /// fn foo(x: &u8) -> bool {
+    /// ```rust
-    ///     true
+    /// fn foo(_x: &u8) {}
-    /// }
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub TOPLEVEL_REF_ARG,
@@ -73,11 +70,12 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let x = 1.0;
-    ///
-    /// // Bad
     /// if x == f32::NAN { }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let x = 1.0f32;
     /// if x.is_nan() { }
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -139,7 +137,8 @@ declare_clippy_lint! {
     /// # let y = String::from("foo");
     /// if x.to_owned() == y {}
     /// ```
-    /// Could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// # let x = "foo";
     /// # let y = String::from("foo");
@@ -232,10 +231,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let a = 0 as *const u32;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let a = std::ptr::null::<u32>();
     /// ```
     #[clippy::version = "pre 1.29.0"]

clippy_lints/src/misc_early/mod.rs

@@ -34,13 +34,21 @@ declare_clippy_lint! {
     /// # }
     /// let f = Foo { a: 0, b: 0, c: 0 };
     ///
-    /// // Bad
     /// match f {
     ///     Foo { a: _, b: 0, .. } => {},
     ///     Foo { a: _, b: _, c: _ } => {},
     /// }
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// # struct Foo {
+    /// #     a: i32,
+    /// #     b: i32,
+    /// #     c: i32,
+    /// # }
+    /// let f = Foo { a: 0, b: 0, c: 0 };
     ///
-    /// // Good
     /// match f {
     ///     Foo { b: 0, .. } => {},
     ///     Foo { .. } => {},
@@ -62,10 +70,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// fn foo(a: i32, _a: i32) {}
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// fn bar(a: i32, _b: i32) {}
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -103,11 +112,16 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let _ =
-    /// let y = 0x1a9BAcD;
+    /// 0x1a9BAcD
+    /// # ;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let y = 0x1A9BACD;
+    /// ```rust
+    /// # let _ =
+    /// 0x1A9BACD
+    /// # ;
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub MIXED_CASE_HEX_LITERALS,
@@ -127,11 +141,16 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let _ =
-    /// let y = 123832i32;
+    /// 123832i32
+    /// # ;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let y = 123832_i32;
+    /// ```rust
+    /// # let _ =
+    /// 123832_i32
+    /// # ;
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub UNSEPARATED_LITERAL_SUFFIX,
@@ -150,11 +169,16 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// # let _ =
-    /// let y = 123832_i32;
+    /// 123832_i32
+    /// # ;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let y = 123832i32;
+    /// ```rust
+    /// # let _ =
+    /// 123832i32
+    /// # ;
     /// ```
     #[clippy::version = "1.58.0"]
     pub SEPARATED_LITERAL_SUFFIX,
@@ -234,14 +258,15 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let v = Some("abc");
-    ///
-    /// // Bad
     /// match v {
     ///     Some(x) => (),
     ///     y @ _ => (),
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let v = Some("abc");
     /// match v {
     ///     Some(x) => (),
     ///     y => (),
@@ -262,6 +287,7 @@ declare_clippy_lint! {
     /// means there are 0 or more elements left. This can make a difference
     /// when refactoring, but shouldn't result in errors in the refactored code,
     /// since the wildcard pattern isn't used anyway.
+    ///
     /// ### Why is this bad?
     /// The wildcard pattern is unneeded as the rest pattern
     /// can match that element as well.
@@ -270,13 +296,16 @@ declare_clippy_lint! {
     /// ```rust
     /// # struct TupleStruct(u32, u32, u32);
     /// # let t = TupleStruct(1, 2, 3);
-    /// // Bad
     /// match t {
     ///     TupleStruct(0, .., _) => (),
     ///     _ => (),
     /// }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # struct TupleStruct(u32, u32, u32);
+    /// # let t = TupleStruct(1, 2, 3);
     /// match t {
     ///     TupleStruct(0, ..) => (),
     ///     _ => (),

clippy_lints/src/mixed_read_write_in_expression.rs

@@ -25,14 +25,16 @@ declare_clippy_lint! {
     /// ```rust
     /// let mut x = 0;
     ///
-    /// // Bad
     /// let a = {
     ///     x = 1;
     ///     1
     /// } + x;
     /// // Unclear whether a is 1 or 2.
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let mut x = 0;
     /// let tmp = {
     ///     x = 1;
     ///     1

clippy_lints/src/mut_reference.rs

@@ -16,12 +16,17 @@ declare_clippy_lint! {
     /// the value. Also the code misleads about the intent of the call site.
     ///
     /// ### Example
-    /// ```ignore
+    /// ```rust
-    /// // Bad
+    /// # let mut vec = Vec::new();
-    /// my_vec.push(&mut value)
+    /// # let mut value = 5;
+    /// vec.push(&mut value);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// my_vec.push(&value)
+    /// ```rust
+    /// # let mut vec = Vec::new();
+    /// # let value = 5;
+    /// vec.push(&value);
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub UNNECESSARY_MUT_PASSED,

clippy_lints/src/mutex_atomic.rs

@@ -27,12 +27,13 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let y = true;
-    ///
-    /// // Bad
     /// # use std::sync::Mutex;
     /// let x = Mutex::new(&y);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let y = true;
     /// # use std::sync::atomic::AtomicBool;
     /// let x = AtomicBool::new(y);
     /// ```
@@ -60,8 +61,10 @@ declare_clippy_lint! {
     /// ```rust
     /// # use std::sync::Mutex;
     /// let x = Mutex::new(0usize);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// # use std::sync::atomic::AtomicUsize;
     /// let x = AtomicUsize::new(0usize);
     /// ```

clippy_lints/src/needless_bool.rs

@@ -30,16 +30,22 @@ declare_clippy_lint! {
     /// shorter code.
     ///
     /// ### Example
-    /// ```rust,ignore
+    /// ```rust
+    /// # let x = true;
     /// if x {
     ///     false
+    /// # ;
     /// } else {
     ///     true
+    /// # ;
     /// }
     /// ```
-    /// Could be written as
+    ///
-    /// ```rust,ignore
+    /// Use instead:
+    /// ```rust
+    /// # let x = true;
     /// !x
+    /// # ;
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub NEEDLESS_BOOL,

clippy_lints/src/needless_borrowed_ref.rs

@@ -27,16 +27,17 @@ declare_clippy_lint! {
     /// ```
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// let mut v = Vec::<String>::new();
-    /// let _ = v.iter_mut().filter(|&ref a| a.is_empty());
+    /// # let _ =
+    /// v.iter_mut().filter(|&ref a| a.is_empty());
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// let mut v = Vec::<String>::new();
-    /// let _ = v.iter_mut().filter(|a| a.is_empty());
+    /// # let _ =
+    /// v.iter_mut().filter(|a| a.is_empty());
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub NEEDLESS_BORROWED_REFERENCE,

clippy_lints/src/needless_update.rs

@@ -24,16 +24,17 @@ declare_clippy_lint! {
     /// #     z: i32,
     /// # }
     /// # let zero_point = Point { x: 0, y: 0, z: 0 };
-    ///
-    /// // Bad
     /// Point {
     ///     x: 1,
     ///     y: 1,
     ///     z: 1,
     ///     ..zero_point
     /// };
+    /// ```
     ///
-    /// // Ok
+    /// Use instead:
+    /// ```rust,ignore
+    /// // Missing field `z`
     /// Point {
     ///     x: 1,
     ///     y: 1,

clippy_lints/src/neg_cmp_op_on_partial_ord.rs

@@ -19,17 +19,17 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
+    /// let a = 1.0;
+    /// let b = f64::NAN;
+    ///
+    /// let not_less_or_equal = !(a <= b);
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
     /// use std::cmp::Ordering;
-    ///
+    /// # let a = 1.0;
-    /// // Bad
+    /// # let b = f64::NAN;
-    /// let a = 1.0;
-    /// let b = f64::NAN;
-    ///
-    /// let _not_less_or_equal = !(a <= b);
-    ///
-    /// // Good
-    /// let a = 1.0;
-    /// let b = f64::NAN;
     ///
     /// let _not_less_or_equal = match a.partial_cmp(&b) {
     ///     None | Some(Ordering::Greater) => true,

clippy_lints/src/neg_multiply.rs

@@ -19,12 +19,13 @@ declare_clippy_lint! {
     /// This only catches integers (for now).
     ///
     /// ### Example
-    /// ```ignore
+    /// ```rust,ignore
-    /// // Bad
     /// let a = x * -1;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let b = -x;
+    /// ```rust,ignore
+    /// let a = -x;
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub NEG_MULTIPLY,

clippy_lints/src/non_copy_const.rs

@@ -58,12 +58,14 @@ declare_clippy_lint! {
     /// ```rust
     /// use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
     ///
-    /// // Bad.
     /// const CONST_ATOM: AtomicUsize = AtomicUsize::new(12);
     /// CONST_ATOM.store(6, SeqCst); // the content of the atomic is unchanged
     /// assert_eq!(CONST_ATOM.load(SeqCst), 12); // because the CONST_ATOM in these lines are distinct
+    /// ```
     ///
-    /// // Good.
+    /// Use instead:
+    /// ```rust
+    /// # use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
     /// static STATIC_ATOM: AtomicUsize = AtomicUsize::new(15);
     /// STATIC_ATOM.store(9, SeqCst);
     /// assert_eq!(STATIC_ATOM.load(SeqCst), 9); // use a `static` item to refer to the same instance
@@ -104,11 +106,15 @@ declare_clippy_lint! {
     /// use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
     /// const CONST_ATOM: AtomicUsize = AtomicUsize::new(12);
     ///
-    /// // Bad.
     /// CONST_ATOM.store(6, SeqCst); // the content of the atomic is unchanged
     /// assert_eq!(CONST_ATOM.load(SeqCst), 12); // because the CONST_ATOM in these lines are distinct
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
+    /// const CONST_ATOM: AtomicUsize = AtomicUsize::new(12);
     ///
-    /// // Good.
     /// static STATIC_ATOM: AtomicUsize = CONST_ATOM;
     /// STATIC_ATOM.store(9, SeqCst);
     /// assert_eq!(STATIC_ATOM.load(SeqCst), 9); // use a `static` item to refer to the same instance

clippy_lints/src/octal_escapes.rs

@@ -33,11 +33,12 @@ declare_clippy_lint! {
     ///
     /// # Example
     /// ```rust
-    /// // Bad
     /// let one = "\033[1m Bold? \033[0m";  // \033 intended as escape
     /// let two = "\033\0";                 // \033 intended as null-3-3
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let one = "\x1b[1mWill this be bold?\x1b[0m";
     /// let two = "\x0033\x00";
     /// ```

clippy_lints/src/pass_by_ref_or_value.rs

@@ -57,12 +57,11 @@ declare_clippy_lint! {
     /// ### Example
     ///
     /// ```rust
-    /// // Bad
     /// fn foo(v: &u32) {}
     /// ```
     ///
+    /// Use instead:
     /// ```rust
-    /// // Better
     /// fn foo(v: u32) {}
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -89,14 +88,13 @@ declare_clippy_lint! {
     /// #[derive(Clone, Copy)]
     /// struct TooLarge([u8; 2048]);
     ///
-    /// // Bad
     /// fn foo(v: TooLarge) {}
     /// ```
-    /// ```rust
-    /// #[derive(Clone, Copy)]
-    /// struct TooLarge([u8; 2048]);
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # #[derive(Clone, Copy)]
+    /// # struct TooLarge([u8; 2048]);
     /// fn foo(v: &TooLarge) {}
     /// ```
     #[clippy::version = "1.49.0"]

clippy_lints/src/ptr.rs

@@ -48,10 +48,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```ignore
-    /// // Bad
     /// fn foo(&Vec<u32>) { .. }
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```ignore
     /// fn foo(&[u32]) { .. }
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -70,15 +71,18 @@ declare_clippy_lint! {
     /// method instead
     ///
     /// ### Example
-    /// ```ignore
+    /// ```rust,ignore
-    /// // Bad
+    /// use std::ptr;
-    /// if x == ptr::null {
-    ///     ..
-    /// }
     ///
-    /// // Good
+    /// if x == ptr::null {
+    ///     // ..
+    /// }
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust,ignore
     /// if x.is_null() {
-    ///     ..
+    ///     // ..
     /// }
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -129,12 +133,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```ignore
-    /// // Bad. Undefined behavior
+    /// // Undefined behavior
     /// unsafe { std::slice::from_raw_parts(ptr::null(), 0); }
     /// ```
     ///
+    /// Use instead:
     /// ```ignore
-    /// // Good
     /// unsafe { std::slice::from_raw_parts(NonNull::dangling().as_ptr(), 0); }
     /// ```
     #[clippy::version = "1.53.0"]

clippy_lints/src/ranges.rs

@@ -27,11 +27,14 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let x = vec![1];
+    /// # let _ =
     /// x.iter().zip(0..x.len());
     /// ```
-    /// Could be written as
+    ///
+    /// Use instead:
     /// ```rust
     /// # let x = vec![1];
+    /// # let _ =
     /// x.iter().enumerate();
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -65,12 +68,21 @@ declare_clippy_lint! {
     /// ([#3307](https://github.com/rust-lang/rust-clippy/issues/3307)).
     ///
     /// ### Example
-    /// ```rust,ignore
+    /// ```rust
-    /// for x..(y+1) { .. }
+    /// # let x = 0;
+    /// # let y = 1;
+    /// for i in x..(y+1) {
+    ///     // ..
+    /// }
     /// ```
-    /// Could be written as
+    ///
-    /// ```rust,ignore
+    /// Use instead:
-    /// for x..=y { .. }
+    /// ```rust
+    /// # let x = 0;
+    /// # let y = 1;
+    /// for i in x..=y {
+    ///     // ..
+    /// }
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub RANGE_PLUS_ONE,
@@ -94,12 +106,21 @@ declare_clippy_lint! {
     /// ([#3307](https://github.com/rust-lang/rust-clippy/issues/3307)).
     ///
     /// ### Example
-    /// ```rust,ignore
+    /// ```rust
-    /// for x..=(y-1) { .. }
+    /// # let x = 0;
+    /// # let y = 1;
+    /// for i in x..=(y-1) {
+    ///     // ..
+    /// }
     /// ```
-    /// Could be written as
+    ///
-    /// ```rust,ignore
+    /// Use instead:
-    /// for x..y { .. }
+    /// ```rust
+    /// # let x = 0;
+    /// # let y = 1;
+    /// for i in x..y {
+    ///     // ..
+    /// }
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub RANGE_MINUS_ONE,

clippy_lints/src/redundant_closure_call.rs

@@ -23,12 +23,13 @@ declare_clippy_lint! {
     /// complexity.
     ///
     /// ### Example
-    /// ```rust,ignore
+    /// ```rust
-    /// // Bad
+    /// let a = (|| 42)();
-    /// let a = (|| 42)()
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let a = 42
+    /// ```rust
+    /// let a = 42;
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub REDUNDANT_CLOSURE_CALL,

clippy_lints/src/reference.rs

@@ -21,11 +21,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// let a = f(*&mut b);
     /// let c = *&d;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust,ignore
     /// let a = f(b);
     /// let c = d;
     /// ```

clippy_lints/src/return_self_not_must_use.rs

@@ -26,19 +26,20 @@ declare_clippy_lint! {
     /// if it was added on constructors for example.
     ///
     /// ### Example
-    /// Missing attribute
     /// ```rust
     /// pub struct Bar;
     /// impl Bar {
-    ///     // Bad
+    ///     // Missing attribute
     ///     pub fn bar(&self) -> Self {
     ///         Self
     ///     }
     /// }
     /// ```
     ///
-    /// It's better to have the `#[must_use]` attribute on the method like this:
+    /// Use instead:
     /// ```rust
+    /// # {
+    /// // It's better to have the `#[must_use]` attribute on the method like this:
     /// pub struct Bar;
     /// impl Bar {
     ///     #[must_use]
@@ -46,10 +47,10 @@ declare_clippy_lint! {
     ///         Self
     ///     }
     /// }
-    /// ```
+    /// # }
     ///
-    /// Or on the type definition like this:
+    /// # {
-    /// ```rust
+    /// // Or on the type definition like this:
     /// #[must_use]
     /// pub struct Bar;
     /// impl Bar {
@@ -57,6 +58,7 @@ declare_clippy_lint! {
     ///         Self
     ///     }
     /// }
+    /// # }
     /// ```
     #[clippy::version = "1.59.0"]
     pub RETURN_SELF_NOT_MUST_USE,

clippy_lints/src/shadow.rs

@@ -23,10 +23,12 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let x = 1;
-    /// // Bad
     /// let x = &x;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let x = 1;
     /// let y = &x; // use different variable name
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -79,11 +81,14 @@ declare_clippy_lint! {
     /// # let y = 1;
     /// # let z = 2;
     /// let x = y;
-    ///
-    /// // Bad
     /// let x = z; // shadows the earlier binding
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let y = 1;
+    /// # let z = 2;
+    /// let x = y;
     /// let w = z; // use different variable name
     /// ```
     #[clippy::version = "pre 1.29.0"]

clippy_lints/src/slow_vector_initialization.rs

@@ -23,15 +23,16 @@ declare_clippy_lint! {
     /// ```rust
     /// # use core::iter::repeat;
     /// # let len = 4;
-    ///
-    /// // Bad
     /// let mut vec1 = Vec::with_capacity(len);
     /// vec1.resize(len, 0);
     ///
     /// let mut vec2 = Vec::with_capacity(len);
     /// vec2.extend(repeat(0).take(len));
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let len = 4;
     /// let mut vec1 = vec![0; len];
     /// let mut vec2 = vec![0; len];
     /// ```

clippy_lints/src/strings.rs

@@ -99,11 +99,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
+    /// let bstr = "a byte string".as_bytes();
-    /// let bs = "a byte string".as_bytes();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
-    /// let bs = b"a byte string";
+    /// ```rust
+    /// let bstr = b"a byte string";
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub STRING_LIT_AS_BYTES,
@@ -223,11 +224,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// let _ = std::str::from_utf8(&"Hello World!".as_bytes()[6..11]).unwrap();
+    /// # let _ =
+    /// std::str::from_utf8(&"Hello World!".as_bytes()[6..11]).unwrap();
     /// ```
-    /// could be written as
+    ///
+    /// Use instead:
     /// ```rust
-    /// let _ = &"Hello World!"[6..11];
+    /// # let _ =
+    /// &"Hello World!"[6..11];
     /// ```
     #[clippy::version = "1.50.0"]
     pub STRING_FROM_UTF8_AS_BYTES,

clippy_lints/src/trait_bounds.rs

@@ -29,8 +29,7 @@ declare_clippy_lint! {
     /// pub fn foo<T>(t: T) where T: Copy, T: Clone {}
     /// ```
     ///
-    /// Could be written as:
+    /// Use instead:
-    ///
     /// ```rust
     /// pub fn foo<T>(t: T) where T: Copy + Clone {}
     /// ```

clippy_lints/src/unicode.rs

@@ -41,7 +41,8 @@ declare_clippy_lint! {
     /// ```rust
     /// let x = String::from("€");
     /// ```
-    /// Could be written as:
+    ///
+    /// Use instead:
     /// ```rust
     /// let x = String::from("\u{20ac}");
     /// ```

clippy_lints/src/unused_async.rs

@@ -17,13 +17,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// async fn get_random_number() -> i64 {
     ///     4 // Chosen by fair dice roll. Guaranteed to be random.
     /// }
     /// let number_future = get_random_number();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// fn get_random_number_improved() -> i64 {
     ///     4 // Chosen by fair dice roll. Guaranteed to be random.
     /// }

clippy_lints/src/useless_conversion.rs

@@ -21,11 +21,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// // format!() returns a `String`
     /// let s: String = format!("hello").into();
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let s: String = format!("hello");
     /// ```
     #[clippy::version = "1.45.0"]

clippy_lints/src/utils/internal_lints.rs

@@ -89,12 +89,11 @@ declare_clippy_lint! {
     /// warning/error messages.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// cx.span_lint(LINT_NAME, "message");
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// utils::span_lint(cx, LINT_NAME, "message");
     /// ```
@@ -112,12 +111,11 @@ declare_clippy_lint! {
     /// `cx.outer_expn_data()` is faster and more concise.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// expr.span.ctxt().outer().expn_data()
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// expr.span.ctxt().outer_expn_data()
     /// ```
@@ -135,7 +133,6 @@ declare_clippy_lint! {
     /// ICE in large quantities can damage your teeth
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// 🍦🍦🍦🍦🍦
     /// ```
@@ -153,12 +150,11 @@ declare_clippy_lint! {
     /// Indicates that the lint is not finished.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// declare_lint! { pub COOL_LINT, nursery, "default lint description" }
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// declare_lint! { pub COOL_LINT, nursery, "a great new lint" }
     /// ```
@@ -183,7 +179,6 @@ declare_clippy_lint! {
     /// convenient, readable and less error prone.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// span_lint_and_then(cx, TEST_LINT, expr.span, lint_msg, |diag| {
     ///     diag.span_suggestion(
@@ -207,7 +202,7 @@ declare_clippy_lint! {
     /// });
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// span_lint_and_sugg(
     ///     cx,
@@ -237,12 +232,11 @@ declare_clippy_lint! {
     /// `utils::is_type_diagnostic_item()` does not require hardcoded paths.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// utils::match_type(cx, ty, &paths::VEC)
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// utils::is_type_diagnostic_item(cx, ty, sym::Vec)
     /// ```
@@ -273,12 +267,11 @@ declare_clippy_lint! {
     /// It's faster and easier to use the symbol constant.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// let _ = sym!(f32);
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// let _ = sym::f32;
     /// ```
@@ -295,12 +288,11 @@ declare_clippy_lint! {
     /// It's faster use symbols directly instead of strings.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust,ignore
     /// symbol.as_str() == "clippy";
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust,ignore
     /// symbol == sym::clippy;
     /// ```

clippy_lints/src/vec.rs

@@ -28,12 +28,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// # fn foo(my_vec: &[u8]) {}
+    /// fn foo(_x: &[u8]) {}
     ///
-    /// // Bad
     /// foo(&vec![1, 2]);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # fn foo(_x: &[u8]) {}
     /// foo(&[1, 2]);
     /// ```
     #[clippy::version = "pre 1.29.0"]

clippy_lints/src/wildcard_imports.rs

@@ -26,13 +26,18 @@ declare_clippy_lint! {
     /// still around.
     ///
     /// ### Example
-    /// ```rust,ignore
+    /// ```rust
-    /// // Bad
     /// use std::cmp::Ordering::*;
-    /// foo(Less);
     ///
-    /// // Good
+    /// # fn foo(_: std::cmp::Ordering) {}
+    /// foo(Less);
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
     /// use std::cmp::Ordering;
+    ///
+    /// # fn foo(_: Ordering) {}
     /// foo(Ordering::Less)
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -76,14 +81,13 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust,ignore
-    /// // Bad
     /// use crate1::*;
     ///
     /// foo();
     /// ```
     ///
+    /// Use instead:
     /// ```rust,ignore
-    /// // Good
     /// use crate1::foo;
     ///
     /// foo();

clippy_lints/src/write.rs

@@ -25,10 +25,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// println!("");
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// println!();
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -177,10 +178,15 @@ declare_clippy_lint! {
     /// ```rust
     /// # use std::fmt::Write;
     /// # let mut buf = String::new();
-    /// // Bad
+    /// # let _ =
     /// writeln!(buf, "");
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # use std::fmt::Write;
+    /// # let mut buf = String::new();
+    /// # let _ =
     /// writeln!(buf);
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -204,10 +210,16 @@ declare_clippy_lint! {
     /// # use std::fmt::Write;
     /// # let mut buf = String::new();
     /// # let name = "World";
-    /// // Bad
+    /// # let _ =
     /// write!(buf, "Hello {}!\n", name);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # use std::fmt::Write;
+    /// # let mut buf = String::new();
+    /// # let name = "World";
+    /// # let _ =
     /// writeln!(buf, "Hello {}!", name);
     /// ```
     #[clippy::version = "pre 1.29.0"]
@@ -233,10 +245,15 @@ declare_clippy_lint! {
     /// ```rust
     /// # use std::fmt::Write;
     /// # let mut buf = String::new();
-    /// // Bad
+    /// # let _ =
     /// writeln!(buf, "{}", "foo");
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # use std::fmt::Write;
+    /// # let mut buf = String::new();
+    /// # let _ =
     /// writeln!(buf, "foo");
     /// ```
     #[clippy::version = "pre 1.29.0"]

clippy_lints/src/zero_div_zero.rs

@@ -14,10 +14,11 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let nan = 0.0f32 / 0.0;
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let nan = f32::NAN;
     /// ```
     #[clippy::version = "pre 1.29.0"]