Auto merge of #8908 - Serial-ATA:doc-comment-issues, r=xFrednet

Make docs more consistent

changelog: none

This just fixes some docs to make them more consistent. I mostly just changed `// Good`, `// Bad`, etc to `Use instead:`.

Author: bors

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,15 +29,14 @@ declare_clippy_lint! {
     /// f(a as u16);
     /// ```
     ///
-    /// Usually better represents the semantics you expect:
+    /// 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,

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

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,20 +234,20 @@ declare_clippy_lint! {
     /// by the conditional compilation engine.
     ///
     /// ### Example
-    /// Bad:
     /// ```rust
     /// #[cfg(linux)]
     /// fn conditional() { }
     /// ```
     ///
-    /// Good:
+    /// Use instead:
     /// ```rust
+    /// # mod hidden {
     /// #[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

@@ -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 { /* ... */ }
     /// ```

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,

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;