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] 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 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 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 = 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 = Ok(1); @@ -245,7 +245,7 @@ declare_clippy_lint! { /// opt?; /// ``` /// - /// // or + /// or /// /// ```rust /// # let res: Result = Ok(1); @@ -440,7 +440,7 @@ declare_clippy_lint! { /// x.map_or(0, |a| a + 1); /// ``` /// - /// // or + /// or /// /// ```rust /// # let x: Result = Ok(1);