Make docs more consistent

29 files changed, 109 insertions, 68 deletions

diff --git a/clippy_lints/src/approx_const.rs b/clippy_lints/src/approx_const.rs
index da1b646f477..159f3b0cd01 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 88b91d58907..5fa8934c71b 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 4c2d3366483..f81da2d4223 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;
+    /// ```
+    ///
+    /// Use instead:
+    /// ```rust
+    /// let mut a = 5;
+    /// let b = 0;
+    /// // ...
     ///
-    /// // Good
     /// a += b;
     /// ```
     #[clippy::version = "pre 1.29.0"]
diff --git a/clippy_lints/src/attrs.rs b/clippy_lints/src/attrs.rs
index 7105ce4b292..79a5b670fc8 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 4c4dd85d518..86e28ea7f7a 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 0adb6327164..e4e122ba6eb 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 02d97bf43df..bfdbaf2413a 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 317c4bfb322..33c44f8b2db 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 3227e6e86af..3eceb848822 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 399d11472b0..913e081af3b 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 e6a0162fd02..1e9a1153011 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 34a5f8444de..e98691fd5bb 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 be95375789d..ee0440e52ff 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 09318f74527..d85ace3a279 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);
-    ///
-    /// // Bad
-    /// let _micros = dur.subsec_nanos() / 1_000;
-    /// let _millis = dur.subsec_nanos() / 1_000_000;
+    /// # let duration = Duration::new(5, 0);
+    /// let micros = duration.subsec_nanos() / 1_000;
+    /// let millis = duration.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 0b9f54231c5..bf4488570ea 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 b5d6b3c7524..bbebc024414 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 c5a987842c3..27743a0ebec 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 e029b8e8537..263a5b573c9 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 cf47e581ccb..ef1216358dd 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 af591dd71aa..b0854ed9bbb 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 7a81fb37e84..a2af10e2ba5 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 3e2217c28da..6b9805efbcf 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 9f868df3ad0..b88e53aeca6 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 7a4397a7b74..f850ea31f4d 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 42503c26de1..df9b41d2c98 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 64c41b56587..3084c70589f 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 57964b8d48e..db0166da57f 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 75d771f992a..417248e31ae 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 b820b740930..eb1bce8c7d2 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);