Skip to content

Make docs more consistent #8908

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 2, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion clippy_lints/src/approx_const.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
9 changes: 4 additions & 5 deletions clippy_lints/src/as_conversions.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
10 changes: 8 additions & 2 deletions clippy_lints/src/assign_ops.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
36 changes: 19 additions & 17 deletions clippy_lints/src/attrs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand Down Expand Up @@ -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)]
Expand All @@ -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)]
/// ```
Expand All @@ -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() { }
Expand All @@ -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() { }
/// ```
Expand All @@ -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)]
///
Expand Down
12 changes: 4 additions & 8 deletions clippy_lints/src/blocks_in_if_conditions.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 { /* ... */ }
/// ```
Expand Down
19 changes: 15 additions & 4 deletions clippy_lints/src/booleans.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand Down
8 changes: 7 additions & 1 deletion clippy_lints/src/bytecount.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/cognitive_complexity.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/collapsible_if.rs
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ declare_clippy_lint! {
///
/// ```
///
/// Should be written:
/// Use instead:
///
/// ```rust,ignore
/// if x && y {
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/comparison_chain.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ declare_clippy_lint! {
/// }
/// ```
///
/// Could be written:
/// Use instead:
///
/// ```rust,ignore
/// use std::cmp::Ordering;
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/copies.rs
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ declare_clippy_lint! {
/// };
/// ```
///
/// Could be written as:
/// Use instead:
/// ```ignore
/// println!("Hello World");
/// let foo = if … {
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/derivable_impls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/double_comparison.rs
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ declare_clippy_lint! {
/// if x == y || x < y {}
/// ```
///
/// Could be written as:
/// Use instead:
///
/// ```rust
/// # let x = 1;
Expand Down
14 changes: 6 additions & 8 deletions clippy_lints/src/double_parens.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
18 changes: 10 additions & 8 deletions clippy_lints/src/duration_subsec.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/else_if_without_else.rs
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ declare_clippy_lint! {
/// }
/// ```
///
/// Could be written:
/// Use instead:
///
/// ```rust
/// # fn a() {}
Expand Down
3 changes: 1 addition & 2 deletions clippy_lints/src/empty_enum.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,11 @@ declare_clippy_lint! {
///
///
/// ### Example
/// Bad:
/// ```rust
/// enum Test {}
/// ```
///
/// Good:
/// Use instead:
/// ```rust
/// #![feature(never_type)]
///
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/entry.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
2 changes: 1 addition & 1 deletion clippy_lints/src/enum_variants.rs
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ declare_clippy_lint! {
/// BattenbergCake,
/// }
/// ```
/// Could be written as:
/// Use instead:
/// ```rust
/// enum Cake {
/// BlackForest,
Expand Down
6 changes: 3 additions & 3 deletions clippy_lints/src/eq_op.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
Loading