From cfd0f5592b681957a6bcdc33d90cc82a9a76ceff Mon Sep 17 00:00:00 2001
From: Serial <69764315+Serial-ATA@users.noreply.github.com>
Date: Sat, 28 May 2022 09:22:59 -0400
Subject: [PATCH 1/3] Make docs more consistent

---
 clippy_lints/src/approx_const.rs              |  2 +-
 clippy_lints/src/as_conversions.rs            |  2 +-
 clippy_lints/src/assign_ops.rs                | 12 +++++--
 clippy_lints/src/attrs.rs                     | 32 ++++++++++---------
 clippy_lints/src/blocks_in_if_conditions.rs   |  2 +-
 clippy_lints/src/booleans.rs                  | 19 ++++++++---
 clippy_lints/src/bytecount.rs                 |  8 ++++-
 clippy_lints/src/cognitive_complexity.rs      |  2 +-
 clippy_lints/src/collapsible_if.rs            |  2 +-
 clippy_lints/src/comparison_chain.rs          |  2 +-
 clippy_lints/src/copies.rs                    |  2 +-
 clippy_lints/src/derivable_impls.rs           |  2 +-
 clippy_lints/src/double_comparison.rs         |  2 +-
 clippy_lints/src/duration_subsec.rs           | 18 ++++++-----
 clippy_lints/src/else_if_without_else.rs      |  2 +-
 clippy_lints/src/empty_enum.rs                |  3 +-
 clippy_lints/src/entry.rs                     |  2 +-
 clippy_lints/src/enum_variants.rs             |  2 +-
 clippy_lints/src/equatable_if_let.rs          |  2 +-
 clippy_lints/src/escape.rs                    |  6 ++--
 clippy_lints/src/excessive_bools.rs           |  3 +-
 clippy_lints/src/explicit_write.rs            | 10 +++++-
 clippy_lints/src/fallible_impl_from.rs        |  3 +-
 clippy_lints/src/float_literal.rs             |  5 +--
 clippy_lints/src/floating_point_arithmetic.rs |  3 +-
 clippy_lints/src/format.rs                    |  7 ++--
 clippy_lints/src/formatting.rs                | 16 +++++++---
 clippy_lints/src/loops/mod.rs                 |  2 +-
 clippy_lints/src/methods/mod.rs               |  6 ++--
 29 files changed, 110 insertions(+), 69 deletions(-)

diff --git a/clippy_lints/src/approx_const.rs b/clippy_lints/src/approx_const.rs
index da1b646f4777..159f3b0cd014 100644
--- a/clippy_lints/src/approx_const.rs
+++ b/clippy_lints/src/approx_const.rs
@@ -28,7 +28,7 @@ declare_clippy_lint! {
     /// let x = 3.14;
     /// let y = 1_f64 / x;
     /// ```
-    /// Use predefined constants instead:
+    /// Use instead:
     /// ```rust
     /// let x = std::f32::consts::PI;
     /// let y = std::f64::consts::FRAC_1_PI;
diff --git a/clippy_lints/src/as_conversions.rs b/clippy_lints/src/as_conversions.rs
index 88b91d589074..5fa8934c71bd 100644
--- a/clippy_lints/src/as_conversions.rs
+++ b/clippy_lints/src/as_conversions.rs
@@ -29,7 +29,7 @@ declare_clippy_lint! {
     /// f(a as u16);
     /// ```
     ///
-    /// Usually better represents the semantics you expect:
+    /// Use instead:
     /// ```rust,ignore
     /// f(a.try_into()?);
     /// ```
diff --git a/clippy_lints/src/assign_ops.rs b/clippy_lints/src/assign_ops.rs
index 4c2d3366483a..f81da2d42233 100644
--- a/clippy_lints/src/assign_ops.rs
+++ b/clippy_lints/src/assign_ops.rs
@@ -27,10 +27,16 @@ declare_clippy_lint! {
     /// let mut a = 5;
     /// let b = 0;
     /// // ...
-    /// // Bad
-    /// a = a + b;
     ///
-    /// // Good
+    /// a = a + b;
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// let mut a = 5;
+    /// let b = 0;
+    /// // ...
+    ///
     /// a += b;
     /// ```
     #[clippy::version = "pre 1.29.0"]
diff --git a/clippy_lints/src/attrs.rs b/clippy_lints/src/attrs.rs
index 7105ce4b292a..79a5b670fc8e 100644
--- a/clippy_lints/src/attrs.rs
+++ b/clippy_lints/src/attrs.rs
@@ -89,13 +89,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```ignore
-    /// // Bad
     /// #[deny(dead_code)]
     /// extern crate foo;
     /// #[forbid(dead_code)]
     /// use foo::bar;
+    /// ```
     ///
-    /// // Ok
+    /// Use instead:
+    /// ```rust,ignore
     /// #[allow(unused_imports)]
     /// use foo::baz;
     /// #[allow(unused_imports)]
@@ -146,15 +147,19 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
+    /// #[allow(dead_code)]
+    ///
+    /// fn not_quite_good_code() { }
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
     /// // Good (as inner attribute)
     /// #![allow(dead_code)]
     ///
     /// fn this_is_fine() { }
     ///
-    /// // Bad
-    /// #[allow(dead_code)]
-    ///
-    /// fn not_quite_good_code() { }
+    /// // or
     ///
     /// // Good (as outer attribute)
     /// #[allow(dead_code)]
@@ -175,12 +180,11 @@ declare_clippy_lint! {
     /// These lints should only be enabled on a lint-by-lint basis and with careful consideration.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// #![deny(clippy::restriction)]
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// #![deny(clippy::as_conversions)]
     /// ```
@@ -205,13 +209,12 @@ declare_clippy_lint! {
     /// [#3123](https://github.com/rust-lang/rust-clippy/pull/3123#issuecomment-422321765)
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// #[cfg_attr(rustfmt, rustfmt_skip)]
     /// fn main() { }
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// #[rustfmt::skip]
     /// fn main() { }
@@ -231,19 +234,19 @@ declare_clippy_lint! {
     /// by the conditional compilation engine.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// #[cfg(linux)]
     /// fn conditional() { }
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// #[cfg(target_os = "linux")]
     /// fn conditional() { }
     /// ```
     ///
-    /// Or:
+    /// or
+    ///
     /// ```rust
     /// #[cfg(unix)]
     /// fn conditional() { }
@@ -266,14 +269,13 @@ declare_clippy_lint! {
     /// ensure that others understand the reasoning
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// #![feature(lint_reasons)]
     ///
     /// #![allow(clippy::some_lint)]
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// #![feature(lint_reasons)]
     ///
diff --git a/clippy_lints/src/blocks_in_if_conditions.rs b/clippy_lints/src/blocks_in_if_conditions.rs
index 4c4dd85d518a..86e28ea7f7a9 100644
--- a/clippy_lints/src/blocks_in_if_conditions.rs
+++ b/clippy_lints/src/blocks_in_if_conditions.rs
@@ -29,7 +29,7 @@ declare_clippy_lint! {
     /// if true { /* ... */ }
     /// ```
     ///
-    /// // or
+    /// or
     ///
     /// ```rust
     /// # fn somefunc() -> bool { true };
diff --git a/clippy_lints/src/booleans.rs b/clippy_lints/src/booleans.rs
index 0adb6327164e..e4e122ba6eb5 100644
--- a/clippy_lints/src/booleans.rs
+++ b/clippy_lints/src/booleans.rs
@@ -27,8 +27,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```ignore
-    /// if a && true  // should be: if a
-    /// if !(a == b)  // should be: if a != b
+    /// if a && true {}
+    /// if !(a == b) {}
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust,ignore
+    /// if a {}
+    /// if a != b {}
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub NONMINIMAL_BOOL,
@@ -48,10 +54,15 @@ declare_clippy_lint! {
     /// Ignores short circuiting behavior.
     ///
     /// ### Example
-    /// ```ignore
+    /// ```rust,ignore
+    /// // The `b` is unnecessary, the expression is equivalent to `if a`.
     /// if a && b || a { ... }
     /// ```
-    /// The `b` is unnecessary, the expression is equivalent to `if a`.
+    ///
+    /// Use instead:
+    /// ```rust,ignore
+    /// if a {}
+    /// ```
     #[clippy::version = "pre 1.29.0"]
     pub LOGIC_BUG,
     correctness,
diff --git a/clippy_lints/src/bytecount.rs b/clippy_lints/src/bytecount.rs
index 02d97bf43df8..bfdbaf2413a2 100644
--- a/clippy_lints/src/bytecount.rs
+++ b/clippy_lints/src/bytecount.rs
@@ -28,7 +28,13 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let vec = vec![1_u8];
-    /// &vec.iter().filter(|x| **x == 0u8).count(); // use bytecount::count instead
+    /// let count = vec.iter().filter(|x| **x == 0u8).count();
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust,ignore
+    /// # let vec = vec![1_u8];
+    /// let count = bytecount::count(&vec, 0u8);
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub NAIVE_BYTECOUNT,
diff --git a/clippy_lints/src/cognitive_complexity.rs b/clippy_lints/src/cognitive_complexity.rs
index 317c4bfb3226..33c44f8b2dba 100644
--- a/clippy_lints/src/cognitive_complexity.rs
+++ b/clippy_lints/src/cognitive_complexity.rs
@@ -25,7 +25,7 @@ declare_clippy_lint! {
     /// complexity.
     ///
     /// ### Example
-    /// No. You'll see it when you get the warning.
+    /// You'll see it when you get the warning.
     #[clippy::version = "1.35.0"]
     pub COGNITIVE_COMPLEXITY,
     nursery,
diff --git a/clippy_lints/src/collapsible_if.rs b/clippy_lints/src/collapsible_if.rs
index 3227e6e86af4..3eceb848822e 100644
--- a/clippy_lints/src/collapsible_if.rs
+++ b/clippy_lints/src/collapsible_if.rs
@@ -41,7 +41,7 @@ declare_clippy_lint! {
     ///
     /// ```
     ///
-    /// Should be written:
+    /// Use instead:
     ///
     /// ```rust,ignore
     /// if x && y {
diff --git a/clippy_lints/src/comparison_chain.rs b/clippy_lints/src/comparison_chain.rs
index 399d11472b09..913e081af3bd 100644
--- a/clippy_lints/src/comparison_chain.rs
+++ b/clippy_lints/src/comparison_chain.rs
@@ -34,7 +34,7 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
-    /// Could be written:
+    /// Use instead:
     ///
     /// ```rust,ignore
     /// use std::cmp::Ordering;
diff --git a/clippy_lints/src/copies.rs b/clippy_lints/src/copies.rs
index e6a0162fd027..1e9a11530110 100644
--- a/clippy_lints/src/copies.rs
+++ b/clippy_lints/src/copies.rs
@@ -141,7 +141,7 @@ declare_clippy_lint! {
     /// };
     /// ```
     ///
-    /// Could be written as:
+    /// Use instead:
     /// ```ignore
     /// println!("Hello World");
     /// let foo = if … {
diff --git a/clippy_lints/src/derivable_impls.rs b/clippy_lints/src/derivable_impls.rs
index 34a5f8444dea..e98691fd5bb0 100644
--- a/clippy_lints/src/derivable_impls.rs
+++ b/clippy_lints/src/derivable_impls.rs
@@ -21,7 +21,7 @@ declare_clippy_lint! {
     ///     bar: bool
     /// }
     ///
-    /// impl std::default::Default for Foo {
+    /// impl Default for Foo {
     ///     fn default() -> Self {
     ///         Self {
     ///             bar: false
diff --git a/clippy_lints/src/double_comparison.rs b/clippy_lints/src/double_comparison.rs
index be95375789d5..ee0440e52ff8 100644
--- a/clippy_lints/src/double_comparison.rs
+++ b/clippy_lints/src/double_comparison.rs
@@ -24,7 +24,7 @@ declare_clippy_lint! {
     /// if x == y || x < y {}
     /// ```
     ///
-    /// Could be written as:
+    /// Use instead:
     ///
     /// ```rust
     /// # let x = 1;
diff --git a/clippy_lints/src/duration_subsec.rs b/clippy_lints/src/duration_subsec.rs
index 09318f74527c..d85ace3a279b 100644
--- a/clippy_lints/src/duration_subsec.rs
+++ b/clippy_lints/src/duration_subsec.rs
@@ -22,15 +22,17 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # use std::time::Duration;
-    /// let dur = Duration::new(5, 0);
+    /// # let duration = Duration::new(5, 0);
+    /// let micros = duration.subsec_nanos() / 1_000;
+    /// let millis = duration.subsec_nanos() / 1_000_000;
+    /// ```
     ///
-    /// // Bad
-    /// let _micros = dur.subsec_nanos() / 1_000;
-    /// let _millis = dur.subsec_nanos() / 1_000_000;
-    ///
-    /// // Good
-    /// let _micros = dur.subsec_micros();
-    /// let _millis = dur.subsec_millis();
+    /// Use instead:
+    /// ```rust
+    /// # use std::time::Duration;
+    /// # let duration = Duration::new(5, 0);
+    /// let micros = duration.subsec_micros();
+    /// let millis = duration.subsec_millis();
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub DURATION_SUBSEC,
diff --git a/clippy_lints/src/else_if_without_else.rs b/clippy_lints/src/else_if_without_else.rs
index 0b9f54231c59..bf4488570eaf 100644
--- a/clippy_lints/src/else_if_without_else.rs
+++ b/clippy_lints/src/else_if_without_else.rs
@@ -26,7 +26,7 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
-    /// Could be written:
+    /// Use instead:
     ///
     /// ```rust
     /// # fn a() {}
diff --git a/clippy_lints/src/empty_enum.rs b/clippy_lints/src/empty_enum.rs
index b5d6b3c7524b..bbebc0244141 100644
--- a/clippy_lints/src/empty_enum.rs
+++ b/clippy_lints/src/empty_enum.rs
@@ -23,12 +23,11 @@ declare_clippy_lint! {
     ///
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// enum Test {}
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// #![feature(never_type)]
     ///
diff --git a/clippy_lints/src/entry.rs b/clippy_lints/src/entry.rs
index c5a987842c3f..27743a0ebec7 100644
--- a/clippy_lints/src/entry.rs
+++ b/clippy_lints/src/entry.rs
@@ -46,7 +46,7 @@ declare_clippy_lint! {
     ///     map.insert(k, v);
     /// }
     /// ```
-    /// can both be rewritten as:
+    /// Use instead:
     /// ```rust
     /// # use std::collections::HashMap;
     /// # let mut map = HashMap::new();
diff --git a/clippy_lints/src/enum_variants.rs b/clippy_lints/src/enum_variants.rs
index e029b8e85379..263a5b573c9c 100644
--- a/clippy_lints/src/enum_variants.rs
+++ b/clippy_lints/src/enum_variants.rs
@@ -32,7 +32,7 @@ declare_clippy_lint! {
     ///     BattenbergCake,
     /// }
     /// ```
-    /// Could be written as:
+    /// Use instead:
     /// ```rust
     /// enum Cake {
     ///     BlackForest,
diff --git a/clippy_lints/src/equatable_if_let.rs b/clippy_lints/src/equatable_if_let.rs
index cf47e581ccb4..ef1216358dd9 100644
--- a/clippy_lints/src/equatable_if_let.rs
+++ b/clippy_lints/src/equatable_if_let.rs
@@ -26,7 +26,7 @@ declare_clippy_lint! {
     ///     do_thing();
     /// }
     /// ```
-    /// Should be written
+    /// Use instead:
     /// ```rust,ignore
     /// if x == Some(2) {
     ///     do_thing();
diff --git a/clippy_lints/src/escape.rs b/clippy_lints/src/escape.rs
index af591dd71aa1..b0854ed9bbb4 100644
--- a/clippy_lints/src/escape.rs
+++ b/clippy_lints/src/escape.rs
@@ -31,12 +31,14 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # fn foo(bar: usize) {}
-    /// // Bad
     /// let x = Box::new(1);
     /// foo(*x);
     /// println!("{}", *x);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # fn foo(bar: usize) {}
     /// let x = 1;
     /// foo(x);
     /// println!("{}", x);
diff --git a/clippy_lints/src/excessive_bools.rs b/clippy_lints/src/excessive_bools.rs
index 7a81fb37e841..a2af10e2ba5e 100644
--- a/clippy_lints/src/excessive_bools.rs
+++ b/clippy_lints/src/excessive_bools.rs
@@ -18,7 +18,6 @@ declare_clippy_lint! {
     /// readability and API.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// struct S {
     ///     is_pending: bool,
@@ -27,7 +26,7 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
     /// enum S {
     ///     Pending,
diff --git a/clippy_lints/src/explicit_write.rs b/clippy_lints/src/explicit_write.rs
index 3e2217c28da3..6b9805efbcfc 100644
--- a/clippy_lints/src/explicit_write.rs
+++ b/clippy_lints/src/explicit_write.rs
@@ -21,8 +21,16 @@ declare_clippy_lint! {
     /// ```rust
     /// # use std::io::Write;
     /// # let bar = "furchtbar";
-    /// // this would be clearer as `eprintln!("foo: {:?}", bar);`
     /// writeln!(&mut std::io::stderr(), "foo: {:?}", bar).unwrap();
+    /// writeln!(&mut std::io::stdout(), "foo: {:?}", bar).unwrap();
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// # use std::io::Write;
+    /// # let bar = "furchtbar";
+    /// eprintln!("foo: {:?}", bar);
+    /// println!("foo: {:?}", bar);
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub EXPLICIT_WRITE,
diff --git a/clippy_lints/src/fallible_impl_from.rs b/clippy_lints/src/fallible_impl_from.rs
index 9f868df3ad06..b88e53aeca69 100644
--- a/clippy_lints/src/fallible_impl_from.rs
+++ b/clippy_lints/src/fallible_impl_from.rs
@@ -20,7 +20,6 @@ declare_clippy_lint! {
     /// ```rust
     /// struct Foo(i32);
     ///
-    /// // Bad
     /// impl From<String> for Foo {
     ///     fn from(s: String) -> Self {
     ///         Foo(s.parse().unwrap())
@@ -28,8 +27,8 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
+    /// Use instead:
     /// ```rust
-    /// // Good
     /// struct Foo(i32);
     ///
     /// impl TryFrom<String> for Foo {
diff --git a/clippy_lints/src/float_literal.rs b/clippy_lints/src/float_literal.rs
index 7a4397a7b746..f850ea31f4d6 100644
--- a/clippy_lints/src/float_literal.rs
+++ b/clippy_lints/src/float_literal.rs
@@ -19,11 +19,12 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// let v: f32 = 0.123_456_789_9;
     /// println!("{}", v); //  0.123_456_789
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
     /// let v: f64 = 0.123_456_789_9;
     /// println!("{}", v); //  0.123_456_789_9
     /// ```
diff --git a/clippy_lints/src/floating_point_arithmetic.rs b/clippy_lints/src/floating_point_arithmetic.rs
index 42503c26de1d..df9b41d2c98b 100644
--- a/clippy_lints/src/floating_point_arithmetic.rs
+++ b/clippy_lints/src/floating_point_arithmetic.rs
@@ -35,8 +35,7 @@ declare_clippy_lint! {
     /// let _ = a.exp() - 1.0;
     /// ```
     ///
-    /// is better expressed as
-    ///
+    /// Use instead:
     /// ```rust
     /// let a = 3f32;
     /// let _ = a.cbrt();
diff --git a/clippy_lints/src/format.rs b/clippy_lints/src/format.rs
index 64c41b565878..3084c70589fa 100644
--- a/clippy_lints/src/format.rs
+++ b/clippy_lints/src/format.rs
@@ -25,12 +25,13 @@ declare_clippy_lint! {
     ///
     /// ### Examples
     /// ```rust
-    ///
-    /// // Bad
     /// let foo = "foo";
     /// format!("{}", foo);
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// let foo = "foo";
     /// foo.to_owned();
     /// ```
     #[clippy::version = "pre 1.29.0"]
diff --git a/clippy_lints/src/formatting.rs b/clippy_lints/src/formatting.rs
index 57964b8d48ea..db0166da57f0 100644
--- a/clippy_lints/src/formatting.rs
+++ b/clippy_lints/src/formatting.rs
@@ -36,12 +36,18 @@ declare_clippy_lint! {
     /// This is either a typo in the binary operator or confusing.
     ///
     /// ### Example
-    /// ```rust,ignore
-    /// if foo <- 30 { // this should be `foo < -30` but looks like a different operator
-    /// }
+    /// ```rust
+    /// # let foo = true;
+    /// # let bar = false;
+    /// // &&! looks like a different operator
+    /// if foo &&! bar {}
+    /// ```
     ///
-    /// if foo &&! bar { // this should be `foo && !bar` but looks like a different operator
-    /// }
+    /// Use instead:
+    /// ```rust
+    /// # let foo = true;
+    /// # let bar = false;
+    /// if foo && !bar {}
     /// ```
     #[clippy::version = "1.40.0"]
     pub SUSPICIOUS_UNARY_OP_FORMATTING,
diff --git a/clippy_lints/src/loops/mod.rs b/clippy_lints/src/loops/mod.rs
index 75d771f992a8..417248e31ae8 100644
--- a/clippy_lints/src/loops/mod.rs
+++ b/clippy_lints/src/loops/mod.rs
@@ -192,7 +192,7 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
-    /// // or
+    /// or
     ///
     /// ```rust
     /// # let res: Result<i32, std::io::Error> = Ok(1);
diff --git a/clippy_lints/src/methods/mod.rs b/clippy_lints/src/methods/mod.rs
index b820b7409304..eb1bce8c7d25 100644
--- a/clippy_lints/src/methods/mod.rs
+++ b/clippy_lints/src/methods/mod.rs
@@ -203,7 +203,7 @@ declare_clippy_lint! {
     /// opt.expect("more helpful message");
     /// ```
     ///
-    /// // or
+    /// or
     ///
     /// ```rust
     /// # let res: Result<usize, ()> = Ok(1);
@@ -245,7 +245,7 @@ declare_clippy_lint! {
     /// opt?;
     /// ```
     ///
-    /// // or
+    /// or
     ///
     /// ```rust
     /// # let res: Result<usize, ()> = Ok(1);
@@ -440,7 +440,7 @@ declare_clippy_lint! {
     /// x.map_or(0, |a| a + 1);
     /// ```
     ///
-    /// // or
+    /// or
     ///
     /// ```rust
     /// # let x: Result<usize, ()> = Ok(1);

From adafb6c41620b91ebd131c2c893f7f13caf9b60c Mon Sep 17 00:00:00 2001
From: Serial <69764315+Serial-ATA@users.noreply.github.com>
Date: Sat, 28 May 2022 09:50:14 -0400
Subject: [PATCH 2/3] Update lint creation docs

---
 doc/adding_lints.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/doc/adding_lints.md b/doc/adding_lints.md
index e8f0c338fd58..3e0b1c5c4f78 100644
--- a/doc/adding_lints.md
+++ b/doc/adding_lints.md
@@ -516,11 +516,12 @@ declare_clippy_lint! {
     /// ### Example
     ///
     /// ```rust,ignore
-    /// // Bad
-    /// Insert a short example of code that triggers the lint
-    ///
-    /// // Good
-    /// Insert a short example of improved code that doesn't trigger the lint
+    /// // A short example of code that triggers the lint
+    /// ```
+    /// 
+    /// Use instead:
+    /// ```rust,ignore
+    /// // A short example of improved code that doesn't trigger the lint
     /// ```
     #[clippy::version = "1.29.0"]
     pub FOO_FUNCTIONS,

From b20f95c1a1780934367a019a6adba4ec74895716 Mon Sep 17 00:00:00 2001
From: Serial <69764315+Serial-ATA@users.noreply.github.com>
Date: Wed, 1 Jun 2022 18:36:02 -0400
Subject: [PATCH 3/3] Combine doc examples

---
 clippy_lints/src/as_conversions.rs          |  7 +-
 clippy_lints/src/attrs.rs                   |  6 +-
 clippy_lints/src/blocks_in_if_conditions.rs | 12 +--
 clippy_lints/src/double_parens.rs           | 14 ++-
 clippy_lints/src/eq_op.rs                   |  6 +-
 clippy_lints/src/loops/mod.rs               | 15 ++--
 clippy_lints/src/methods/mod.rs             | 99 +++++++++------------
 clippy_lints/src/minmax.rs                  |  8 +-
 clippy_lints/src/misc.rs                    | 14 ++-
 clippy_lints/src/mutable_debug_assertion.rs |  7 +-
 clippy_lints/src/trait_bounds.rs            | 10 +--
 11 files changed, 88 insertions(+), 110 deletions(-)

diff --git a/clippy_lints/src/as_conversions.rs b/clippy_lints/src/as_conversions.rs
index 5fa8934c71bd..6e5c8f445818 100644
--- a/clippy_lints/src/as_conversions.rs
+++ b/clippy_lints/src/as_conversions.rs
@@ -32,12 +32,11 @@ declare_clippy_lint! {
     /// Use instead:
     /// ```rust,ignore
     /// f(a.try_into()?);
-    /// ```
-    /// or
-    /// ```rust,ignore
+    ///
+    /// // or
+    ///
     /// f(a.try_into().expect("Unexpected u16 overflow in f"));
     /// ```
-    ///
     #[clippy::version = "1.41.0"]
     pub AS_CONVERSIONS,
     restriction,
diff --git a/clippy_lints/src/attrs.rs b/clippy_lints/src/attrs.rs
index 79a5b670fc8e..770cb6a3d7b8 100644
--- a/clippy_lints/src/attrs.rs
+++ b/clippy_lints/src/attrs.rs
@@ -241,13 +241,13 @@ declare_clippy_lint! {
     ///
     /// Use instead:
     /// ```rust
+    /// # mod hidden {
     /// #[cfg(target_os = "linux")]
     /// fn conditional() { }
-    /// ```
+    /// # }
     ///
-    /// or
+    /// // or
     ///
-    /// ```rust
     /// #[cfg(unix)]
     /// fn conditional() { }
     /// ```
diff --git a/clippy_lints/src/blocks_in_if_conditions.rs b/clippy_lints/src/blocks_in_if_conditions.rs
index 86e28ea7f7a9..5bd7a342389f 100644
--- a/clippy_lints/src/blocks_in_if_conditions.rs
+++ b/clippy_lints/src/blocks_in_if_conditions.rs
@@ -22,21 +22,17 @@ declare_clippy_lint! {
     ///
     /// ### Examples
     /// ```rust
-    /// // Bad
+    /// # fn somefunc() -> bool { true };
     /// if { true } { /* ... */ }
     ///
-    /// // Good
-    /// if true { /* ... */ }
+    /// if { let x = somefunc(); x } { /* ... */ }
     /// ```
     ///
-    /// or
-    ///
+    /// Use instead:
     /// ```rust
     /// # fn somefunc() -> bool { true };
-    /// // Bad
-    /// if { let x = somefunc(); x } { /* ... */ }
+    /// if true { /* ... */ }
     ///
-    /// // Good
     /// let res = { let x = somefunc(); x };
     /// if res { /* ... */ }
     /// ```
diff --git a/clippy_lints/src/double_parens.rs b/clippy_lints/src/double_parens.rs
index e10f740d24a4..a33ef5ce6e37 100644
--- a/clippy_lints/src/double_parens.rs
+++ b/clippy_lints/src/double_parens.rs
@@ -13,23 +13,21 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```rust
-    /// // Bad
     /// fn simple_double_parens() -> i32 {
     ///     ((0))
     /// }
     ///
-    /// // Good
+    /// # fn foo(bar: usize) {}
+    /// foo((0));
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
     /// fn simple_no_parens() -> i32 {
     ///     0
     /// }
     ///
-    /// // or
-    ///
     /// # fn foo(bar: usize) {}
-    /// // Bad
-    /// foo((0));
-    ///
-    /// // Good
     /// foo(0);
     /// ```
     #[clippy::version = "pre 1.29.0"]
diff --git a/clippy_lints/src/eq_op.rs b/clippy_lints/src/eq_op.rs
index afb5d32f9533..c3176d987c63 100644
--- a/clippy_lints/src/eq_op.rs
+++ b/clippy_lints/src/eq_op.rs
@@ -30,9 +30,9 @@ declare_clippy_lint! {
     /// ```rust
     /// # let x = 1;
     /// if x + 1 == x + 1 {}
-    /// ```
-    /// or
-    /// ```rust
+    ///
+    /// // or
+    ///
     /// # let a = 3;
     /// # let b = 4;
     /// assert_eq!(a, a);
diff --git a/clippy_lints/src/loops/mod.rs b/clippy_lints/src/loops/mod.rs
index 417248e31ae8..d61be78895ff 100644
--- a/clippy_lints/src/loops/mod.rs
+++ b/clippy_lints/src/loops/mod.rs
@@ -180,29 +180,24 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust
     /// # let opt = Some(1);
-    ///
-    /// // Bad
+    /// # let res: Result<i32, std::io::Error> = Ok(1);
     /// for x in opt {
     ///     // ..
     /// }
     ///
-    /// // Good
-    /// if let Some(x) = opt {
+    /// for x in &res {
     ///     // ..
     /// }
     /// ```
     ///
-    /// or
-    ///
+    /// Use instead:
     /// ```rust
+    /// # let opt = Some(1);
     /// # let res: Result<i32, std::io::Error> = Ok(1);
-    ///
-    /// // Bad
-    /// for x in &res {
+    /// if let Some(x) = opt {
     ///     // ..
     /// }
     ///
-    /// // Good
     /// if let Ok(x) = res {
     ///     // ..
     /// }
diff --git a/clippy_lints/src/methods/mod.rs b/clippy_lints/src/methods/mod.rs
index eb1bce8c7d25..08c89ceb7964 100644
--- a/clippy_lints/src/methods/mod.rs
+++ b/clippy_lints/src/methods/mod.rs
@@ -194,25 +194,18 @@ declare_clippy_lint! {
     ///
     /// ### Examples
     /// ```rust
-    /// # let opt = Some(1);
-    ///
-    /// // Bad
-    /// opt.unwrap();
-    ///
-    /// // Good
-    /// opt.expect("more helpful message");
+    /// # let option = Some(1);
+    /// # let result: Result<usize, ()> = Ok(1);
+    /// option.unwrap();
+    /// result.unwrap();
     /// ```
     ///
-    /// or
-    ///
+    /// Use instead:
     /// ```rust
-    /// # let res: Result<usize, ()> = Ok(1);
-    ///
-    /// // Bad
-    /// res.unwrap();
-    ///
-    /// // Good
-    /// res.expect("more helpful message");
+    /// # let option = Some(1);
+    /// # let result: Result<usize, ()> = Ok(1);
+    /// option.expect("more helpful message");
+    /// result.expect("more helpful message");
     /// ```
     #[clippy::version = "1.45.0"]
     pub UNWRAP_USED,
@@ -235,27 +228,21 @@ declare_clippy_lint! {
     ///
     /// ### Examples
     /// ```rust,ignore
-    /// # let opt = Some(1);
-    ///
-    /// // Bad
-    /// opt.expect("one");
-    ///
-    /// // Good
-    /// let opt = Some(1);
-    /// opt?;
+    /// # let option = Some(1);
+    /// # let result: Result<usize, ()> = Ok(1);
+    /// option.expect("one");
+    /// result.expect("one");
     /// ```
     ///
-    /// or
+    /// Use instead:
+    /// ```rust,ignore
+    /// # let option = Some(1);
+    /// # let result: Result<usize, ()> = Ok(1);
+    /// option?;
     ///
-    /// ```rust
-    /// # let res: Result<usize, ()> = Ok(1);
+    /// // or
     ///
-    /// // Bad
-    /// res.expect("one");
-    ///
-    /// // Good
-    /// res?;
-    /// # Ok::<(), ()>(())
+    /// result?;
     /// ```
     #[clippy::version = "1.45.0"]
     pub EXPECT_USED,
@@ -431,26 +418,20 @@ declare_clippy_lint! {
     ///
     /// ### Examples
     /// ```rust
-    /// # let x = Some(1);
-    ///
-    /// // Bad
-    /// x.map(|a| a + 1).unwrap_or(0);
-    ///
-    /// // Good
-    /// x.map_or(0, |a| a + 1);
+    /// # let option = Some(1);
+    /// # let result: Result<usize, ()> = Ok(1);
+    /// # fn some_function(foo: ()) -> usize { 1 }
+    /// option.map(|a| a + 1).unwrap_or(0);
+    /// result.map(|a| a + 1).unwrap_or_else(some_function);
     /// ```
     ///
-    /// or
-    ///
+    /// Use instead:
     /// ```rust
-    /// # let x: Result<usize, ()> = Ok(1);
+    /// # let option = Some(1);
+    /// # let result: Result<usize, ()> = Ok(1);
     /// # fn some_function(foo: ()) -> usize { 1 }
-    ///
-    /// // Bad
-    /// x.map(|a| a + 1).unwrap_or_else(some_function);
-    ///
-    /// // Good
-    /// x.map_or_else(some_function, |a| a + 1);
+    /// option.map_or(0, |a| a + 1);
+    /// result.map_or_else(some_function, |a| a + 1);
     /// ```
     #[clippy::version = "1.45.0"]
     pub MAP_UNWRAP_OR,
@@ -793,13 +774,14 @@ declare_clippy_lint! {
     /// # let foo = Some(String::new());
     /// foo.unwrap_or(String::new());
     /// ```
-    /// this can instead be written:
+    ///
+    /// Use instead:
     /// ```rust
     /// # let foo = Some(String::new());
     /// foo.unwrap_or_else(String::new);
-    /// ```
-    /// or
-    /// ```rust
+    ///
+    /// // or
+    ///
     /// # let foo = Some(String::new());
     /// foo.unwrap_or_default();
     /// ```
@@ -863,15 +845,14 @@ declare_clippy_lint! {
     /// # let err_code = "418";
     /// # let err_msg = "I'm a teapot";
     /// foo.expect(&format!("Err {}: {}", err_code, err_msg));
-    /// ```
-    /// or
-    /// ```rust
+    ///
+    /// // or
+    ///
     /// # let foo = Some(String::new());
-    /// # let err_code = "418";
-    /// # let err_msg = "I'm a teapot";
     /// foo.expect(format!("Err {}: {}", err_code, err_msg).as_str());
     /// ```
-    /// this can instead be written:
+    ///
+    /// Use instead:
     /// ```rust
     /// # let foo = Some(String::new());
     /// # let err_code = "418";
diff --git a/clippy_lints/src/minmax.rs b/clippy_lints/src/minmax.rs
index 65d1f440b763..a081cde85725 100644
--- a/clippy_lints/src/minmax.rs
+++ b/clippy_lints/src/minmax.rs
@@ -18,11 +18,11 @@ declare_clippy_lint! {
     /// the least it hurts readability of the code.
     ///
     /// ### Example
-    /// ```ignore
+    /// ```rust,ignore
     /// min(0, max(100, x))
-    /// ```
-    /// or
-    /// ```ignore
+    ///
+    /// // or
+    ///
     /// x.max(100).min(0)
     /// ```
     /// It will always be equal to `0`. Probably the author meant to clamp the value
diff --git a/clippy_lints/src/misc.rs b/clippy_lints/src/misc.rs
index 7fdc28c5a062..556656994532 100644
--- a/clippy_lints/src/misc.rs
+++ b/clippy_lints/src/misc.rs
@@ -103,11 +103,14 @@ declare_clippy_lint! {
     /// let x = 1.2331f64;
     /// let y = 1.2332f64;
     ///
-    /// // Bad
     /// if y == 1.23f64 { }
     /// if y != x {} // where both are floats
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let x = 1.2331f64;
+    /// # let y = 1.2332f64;
     /// let error_margin = f64::EPSILON; // Use an epsilon for comparison
     /// // Or, if Rust <= 1.42, use `std::f64::EPSILON` constant instead.
     /// // let error_margin = std::f64::EPSILON;
@@ -258,10 +261,13 @@ declare_clippy_lint! {
     /// let x: f64 = 1.0;
     /// const ONE: f64 = 1.00;
     ///
-    /// // Bad
     /// if x == ONE { } // where both are floats
+    /// ```
     ///
-    /// // Good
+    /// Use instead:
+    /// ```rust
+    /// # let x: f64 = 1.0;
+    /// # const ONE: f64 = 1.00;
     /// let error_margin = f64::EPSILON; // Use an epsilon for comparison
     /// // Or, if Rust <= 1.42, use `std::f64::EPSILON` constant instead.
     /// // let error_margin = std::f64::EPSILON;
diff --git a/clippy_lints/src/mutable_debug_assertion.rs b/clippy_lints/src/mutable_debug_assertion.rs
index 8dba60f3a585..321db08dfe89 100644
--- a/clippy_lints/src/mutable_debug_assertion.rs
+++ b/clippy_lints/src/mutable_debug_assertion.rs
@@ -22,9 +22,12 @@ declare_clippy_lint! {
     /// ### Example
     /// ```rust,ignore
     /// debug_assert_eq!(vec![3].pop(), Some(3));
+    ///
     /// // or
-    /// fn take_a_mut_parameter(_: &mut u32) -> bool { unimplemented!() }
-    /// debug_assert!(take_a_mut_parameter(&mut 5));
+    ///
+    /// # let mut x = 5;
+    /// # fn takes_a_mut_parameter(_: &mut u32) -> bool { unimplemented!() }
+    /// debug_assert!(takes_a_mut_parameter(&mut x));
     /// ```
     #[clippy::version = "1.40.0"]
     pub DEBUG_ASSERT_WITH_MUT_CALL,
diff --git a/clippy_lints/src/trait_bounds.rs b/clippy_lints/src/trait_bounds.rs
index 6c60fb4b8e02..b91be0eb4bed 100644
--- a/clippy_lints/src/trait_bounds.rs
+++ b/clippy_lints/src/trait_bounds.rs
@@ -54,14 +54,14 @@ declare_clippy_lint! {
     /// fn func<T: Clone + Default>(arg: T) where T: Clone + Default {}
     /// ```
     ///
-    /// Could be written as:
-    ///
+    /// Use instead:
     /// ```rust
+    /// # mod hidden {
     /// fn func<T: Clone + Default>(arg: T) {}
-    /// ```
-    /// or
+    /// # }
+    ///
+    /// // or
     ///
-    /// ```rust
     /// fn func<T>(arg: T) where T: Clone + Default {}
     /// ```
     #[clippy::version = "1.47.0"]