Combine doc examples

11 files changed, 88 insertions, 110 deletions

diff --git a/clippy_lints/src/as_conversions.rs b/clippy_lints/src/as_conversions.rs
index 5fa8934c71b..6e5c8f44581 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 79a5b670fc8..770cb6a3d7b 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 86e28ea7f7a..5bd7a342389 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 e10f740d24a..a33ef5ce6e3 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 afb5d32f953..c3176d987c6 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 417248e31ae..d61be78895f 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 eb1bce8c7d2..08c89ceb796 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
-    ///
-    /// ```rust
-    /// # let res: Result<usize, ()> = Ok(1);
+    /// Use instead:
+    /// ```rust,ignore
+    /// # let option = Some(1);
+    /// # let result: Result<usize, ()> = Ok(1);
+    /// option?;
     ///
-    /// // Bad
-    /// res.expect("one");
+    /// // or
     ///
-    /// // 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 65d1f440b76..a081cde8572 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 7fdc28c5a06..55665699453 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 8dba60f3a58..321db08dfe8 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 6c60fb4b8e0..b91be0eb4be 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"]