Make docs more consistent

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;

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()?);
     /// ```

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"]

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
+    /// // or
-    /// #[allow(dead_code)]
-    ///
-    /// fn not_quite_good_code() { }
     ///
     /// // 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)]
     ///

clippy_lints/src/blocks_in_if_conditions.rs

@@ -29,7 +29,7 @@ declare_clippy_lint! {
     /// if true { /* ... */ }
     /// ```
     ///
-    /// // or
+    /// or
     ///
     /// ```rust
     /// # fn somefunc() -> bool { true };

clippy_lints/src/booleans.rs

@@ -27,8 +27,14 @@ declare_clippy_lint! {
     ///
     /// ### Example
     /// ```ignore
-    /// if a && true  // should be: if a
+    /// if a && true {}
-    /// if !(a == b)  // should be: if a != b
+    /// 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,

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,

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,

clippy_lints/src/collapsible_if.rs

@@ -41,7 +41,7 @@ declare_clippy_lint! {
     ///
     /// ```
     ///
-    /// Should be written:
+    /// Use instead:
     ///
     /// ```rust,ignore
     /// if x && y {

clippy_lints/src/comparison_chain.rs

@@ -34,7 +34,7 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
-    /// Could be written:
+    /// Use instead:
     ///
     /// ```rust,ignore
     /// use std::cmp::Ordering;

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 … {

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

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;

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
+    /// Use instead:
-    /// let _micros = dur.subsec_nanos() / 1_000;
+    /// ```rust
-    /// let _millis = dur.subsec_nanos() / 1_000_000;
+    /// # use std::time::Duration;
-    ///
+    /// # let duration = Duration::new(5, 0);
-    /// // Good
+    /// let micros = duration.subsec_micros();
-    /// let _micros = dur.subsec_micros();
+    /// let millis = duration.subsec_millis();
-    /// let _millis = dur.subsec_millis();
     /// ```
     #[clippy::version = "pre 1.29.0"]
     pub DURATION_SUBSEC,

clippy_lints/src/else_if_without_else.rs

@@ -26,7 +26,7 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
-    /// Could be written:
+    /// Use instead:
     ///
     /// ```rust
     /// # fn a() {}

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

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();

clippy_lints/src/enum_variants.rs

@@ -32,7 +32,7 @@ declare_clippy_lint! {
     ///     BattenbergCake,
     /// }
     /// ```
-    /// Could be written as:
+    /// Use instead:
     /// ```rust
     /// enum Cake {
     ///     BlackForest,

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();

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);

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,

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,

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 {

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

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();

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"]

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
+    /// ```rust
-    /// if foo <- 30 { // this should be `foo < -30` but looks like a different operator
+    /// # 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,

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);

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);