add --explain subcommand

Author: llogiq

src/docs.rs

@@ -0,0 +1,21 @@
+### What it does
+Checks for comparisons where one side of the relation is
+either the minimum or maximum value for its type and warns if it involves a
+case that is always true or always false. Only integer and boolean types are
+checked.
+### Why is this bad?
+An expression like `min <= x` may misleadingly imply
+that it is possible for `x` to be less than the minimum. Expressions like
+`max < x` are probably mistakes.
+### Known problems
+For `usize` the size of the current compile target will
+be assumed (e.g., 64 bits on 64 bit systems). This means code that uses such
+a comparison to detect target pointer width will trigger this lint. One can
+use `mem::sizeof` and compare its value or conditional compilation
+attributes
+like `#[cfg(target_pointer_width = "64")] ..` instead.
+### Example
+
+let vec: Vec<isize> = Vec::new();
+if vec.len() <= 0 {}
+if 100 > i32::MAX {}

src/docs/absurd_extreme_comparisons.md

@@ -0,0 +1,13 @@
+### What it does
+Finds items imported through `alloc` when available through `core`.
+### Why is this bad?
+Crates which have `no_std` compatibility and may optionally require alloc may wish to ensure types are
+imported from core to ensure disabling `alloc` does not cause the crate to fail to compile. This lint
+is also useful for crates migrating to become `no_std` compatible.
+### Example
+
+use alloc::slice::from_ref;
+
+Use instead:
+
+use core::slice::from_ref;

src/docs/alloc_instead_of_core.md

@@ -0,0 +1,15 @@
+### What it does
+Checks for attributes that allow lints without a reason.
+(This requires the `lint_reasons` feature)
+### Why is this bad?
+Allowing a lint should always have a reason. This reason should be documented to
+ensure that others understand the reasoning
+### Example
+
+#![feature(lint_reasons)]
+#![allow(clippy::some_lint)]
+
+Use instead:
+
+#![feature(lint_reasons)]
+#![allow(clippy::some_lint, reason = "False positive rust-lang/rust-clippy#1002020")]

src/docs/allow_attributes_without_reason.md

@@ -0,0 +1,12 @@
+### What it does
+Checks for ranges which almost include the entire range of letters from 'a' to 'z', but
+don't because they're a half open range.
+### Why is this bad?
+This (`'a'..'z'`) is almost certainly a typo meant to include all letters.
+### Example
+
+let _ = 'a'..'z';
+
+Use instead:
+
+let _ = 'a'..='z';

src/docs/almost_complete_letter_range.md

@@ -0,0 +1,12 @@
+### What it does
+Checks for `foo = bar; bar = foo` sequences.
+### Why is this bad?
+This looks like a failed attempt to swap.
+### Example
+
+a = b;
+b = a;
+
+If swapping is intended, use `swap()` instead:
+
+std::mem::swap(&mut a, &mut b);

src/docs/almost_swapped.md

@@ -0,0 +1,21 @@
+### What it does
+Checks for floating point literals that approximate
+constants which are defined in
+[`std::f32::consts`](https://doc.rust-lang.org/stable/std/f32/consts/#constants)
+or
+[`std::f64::consts`](https://doc.rust-lang.org/stable/std/f64/consts/#constants),
+respectively, suggesting to use the predefined constant.
+### Why is this bad?
+Usually, the definition in the standard library is more
+precise than what people come up with. If you find that your definition is
+actually more precise, please [file a Rust
+issue](https://github.com/rust-lang/rust/issues).
+### Example
+
+let x = 3.14;
+let y = 1_f64 / x;
+
+Use instead:
+
+let x = std::f32::consts::PI;
+let y = std::f64::consts::FRAC_1_PI;

src/docs/approx_constant.md

@@ -0,0 +1,22 @@
+### What it does
+Checks for any kind of arithmetic operation of any type.
+Operators like `+`, `-`, `*` or `<<` are usually capable of overflowing according to the [Rust
+Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#overflow),
+or can panic (`/`, `%`). Known safe built-in types like `Wrapping` or `Saturing` are filtered
+away.
+### Why is this bad?
+Integer overflow will trigger a panic in debug builds or will wrap in
+release mode. Division by zero will cause a panic in either mode. In some applications one
+wants explicitly checked, wrapping or saturating arithmetic.
+#### Example
+
+a + 1;
+
+Third-party types also tend to overflow.
+#### Example
+
+use rust_decimal::Decimal;
+let _n = Decimal::MAX + Decimal::MAX;
+
+### Allowed types
+Custom allowed types can be specified through the "arithmetic-allowed" filter.

src/docs/arithmetic.md

@@ -0,0 +1,25 @@
+### What it does
+Checks for usage of `as` conversions.
+Note that this lint is specialized in linting *every single* use of `as`
+regardless of whether good alternatives exist or not.
+If you want more precise lints for `as`, please consider using these separate lints:
+`unnecessary_cast`, `cast_lossless/cast_possible_truncation/cast_possible_wrap/cast_precision_loss/cast_sign_loss`,
+`fn_to_numeric_cast(_with_truncation)`, `char_lit_as_u8`, `ref_to_mut` and `ptr_as_ptr`.
+There is a good explanation the reason why this lint should work in this way and how it is useful
+[in this issue](https://github.com/rust-lang/rust-clippy/issues/5122).
+### Why is this bad?
+`as` conversions will perform many kinds of
+conversions, including silently lossy conversions and dangerous coercions.
+There are cases when it makes sense to use `as`, so the lint is
+Allow by default.
+### Example
+
+let a: u32;
+...
+f(a as u16);
+
+Use instead:
+
+f(a.try_into()?);
+// or
+f(a.try_into().expect("Unexpected u16 overflow in f"));

src/docs/as_conversions.md

@@ -0,0 +1,17 @@
+### What it does
+Check for the usage of `as _` conversion using inferred type.
+### Why is this bad?
+The conversion might include lossy conversion and dangerous cast that might go
+undetected due to the type being inferred.
+The lint is allowed by default as using `_` is less wordy than always specifying the type.
+### Example
+
+fn foo(n: usize) {}
+let n: u16 = 256;
+foo(n as _);
+
+Use instead:
+
+fn foo(n: usize) {}
+let n: u16 = 256;
+foo(n as usize);

src/docs/as_underscore.md

@@ -0,0 +1,11 @@
+### What it does
+Checks for `assert!(true)` and `assert!(false)` calls.
+### Why is this bad?
+Will be optimized out by the compiler or should probably be replaced by a
+`panic!()` or `unreachable!()`
+### Example
+
+assert!(false)
+assert!(true)
+const B: bool = false;
+assert!(B)

src/docs/assertions_on_constants.md

@@ -0,0 +1,10 @@
+### What it does
+Checks for `assert!(r.is_ok())` or `assert!(r.is_err())` calls.
+### Why is this bad?
+An assertion failure cannot output an useful message of the error.
+### Known problems
+The suggested replacement decreases the readability of code and log output.
+### Example
+
+assert!(r.is_ok());
+assert!(r.is_err());

src/docs/assertions_on_result_states.md

@@ -0,0 +1,21 @@
+### What it does
+Checks for `a = a op b` or `a = b commutative_op a`
+patterns.
+### Why is this bad?
+These can be written as the shorter `a op= b`.
+### Known problems
+While forbidden by the spec, `OpAssign` traits may have
+implementations that differ from the regular `Op` impl.
+### Example
+
+let mut a = 5;
+let b = 0;
+// ...
+a = a + b;
+
+Use instead:
+
+let mut a = 5;
+let b = 0;
+// ...
+a += b;

src/docs/assign_op_pattern.md

@@ -0,0 +1,22 @@
+### What it does
+Checks for async blocks that yield values of types
+that can themselves be awaited.
+### Why is this bad?
+An await is likely missing.
+### Example
+
+async fn foo() {}
+fn bar() {
+  let x = async {
+    foo()
+  };
+}
+
+Use instead:
+
+async fn foo() {}
+fn bar() {
+  let x = async {
+    foo().await
+  };
+}

src/docs/async_yields_async.md

@@ -0,0 +1,24 @@
+### What it does
+Allows users to configure types which should not be held across `await`
+suspension points.
+### Why is this bad?
+There are some types which are perfectly "safe" to be used concurrently
+from a memory access perspective but will cause bugs at runtime if they
+are held in such a way.
+### Example
+
+await-holding-invalid-types = [
+  # You can specify a type name
+  "CustomLockType",
+  # You can (optionally) specify a reason
+  { path = "OtherCustomLockType", reason = "Relies on a thread local" }
+]
+
+
+struct CustomLockType;
+struct OtherCustomLockType;
+async fn foo() {
+  let _x = CustomLockType;
+  let _y = OtherCustomLockType;
+  baz().await; // Lint violation
+}

src/docs/await_holding_invalid_type.md

@@ -0,0 +1,43 @@
+### What it does
+Checks for calls to await while holding a non-async-aware MutexGuard.
+### Why is this bad?
+The Mutex types found in std::sync and parking_lot
+are not designed to operate in an async context across await points.
+There are two potential solutions. One is to use an async-aware Mutex
+type. Many asynchronous foundation crates provide such a Mutex type. The
+other solution is to ensure the mutex is unlocked before calling await,
+either by introducing a scope or an explicit call to Drop::drop.
+### Known problems
+Will report false positive for explicitly dropped guards
+([#6446](https://github.com/rust-lang/rust-clippy/issues/6446)). A workaround for this is
+to wrap the `.lock()` call in a block instead of explicitly dropping the guard.
+### Example
+
+async fn foo(x: &Mutex<u32>) {
+  let mut guard = x.lock().unwrap();
+  *guard += 1;
+  baz().await;
+}
+async fn bar(x: &Mutex<u32>) {
+  let mut guard = x.lock().unwrap();
+  *guard += 1;
+  drop(guard); // explicit drop
+  baz().await;
+}
+
+Use instead:
+
+async fn foo(x: &Mutex<u32>) {
+  {
+    let mut guard = x.lock().unwrap();
+    *guard += 1;
+  }
+  baz().await;
+}
+async fn bar(x: &Mutex<u32>) {
+  {
+    let mut guard = x.lock().unwrap();
+    *guard += 1;
+  } // guard dropped here at end of scope
+  baz().await;
+}

src/docs/await_holding_lock.md

@@ -0,0 +1,40 @@
+### What it does
+Checks for calls to await while holding a `RefCell` `Ref` or `RefMut`.
+### Why is this bad?
+`RefCell` refs only check for exclusive mutable access
+at runtime. Holding onto a `RefCell` ref across an `await` suspension point
+risks panics from a mutable ref shared while other refs are outstanding.
+### Known problems
+Will report false positive for explicitly dropped refs
+([#6353](https://github.com/rust-lang/rust-clippy/issues/6353)). A workaround for this is
+to wrap the `.borrow[_mut]()` call in a block instead of explicitly dropping the ref.
+### Example
+
+async fn foo(x: &RefCell<u32>) {
+  let mut y = x.borrow_mut();
+  *y += 1;
+  baz().await;
+}
+async fn bar(x: &RefCell<u32>) {
+  let mut y = x.borrow_mut();
+  *y += 1;
+  drop(y); // explicit drop
+  baz().await;
+}
+
+Use instead:
+
+async fn foo(x: &RefCell<u32>) {
+  {
+     let mut y = x.borrow_mut();
+     *y += 1;
+  }
+  baz().await;
+}
+async fn bar(x: &RefCell<u32>) {
+  {
+    let mut y = x.borrow_mut();
+    *y += 1;
+  } // y dropped here at end of scope
+  baz().await;
+}

src/docs/await_holding_refcell_ref.md

@@ -0,0 +1,24 @@
+### What it does
+Checks for incompatible bit masks in comparisons.
+The formula for detecting if an expression of the type `_ <bit_op> m
+<cmp_op> c` (where `<bit_op>` is one of {`&`, `|`} and `<cmp_op>` is one of
+{`!=`, `>=`, `>`, `!=`, `>=`, `>`}) can be determined from the following
+table:
+|Comparison  |Bit Op|Example      |is always|Formula               |
+|------------|------|-------------|---------|----------------------|
+|`==` or `!=`| `&`  |`x & 2 == 3` |`false`  |`c & m != c`          |
+|`<`  or `>=`| `&`  |`x & 2 < 3`  |`true`   |`m < c`               |
+|`>`  or `<=`| `&`  |`x & 1 > 1`  |`false`  |`m <= c`              |
+|`==` or `!=`| `\|` |`x \| 1 == 0`|`false`  |`c \| m != c`         |
+|`<`  or `>=`| `\|` |`x \| 1 < 1` |`false`  |`m >= c`              |
+|`<=` or `>` | `\|` |`x \| 1 > 0` |`true`   |`m > c`               |
+### Why is this bad?
+If the bits that the comparison cares about are always
+set to zero or one by the bit mask, the comparison is constant `true` or
+`false` (depending on mask, compared value, and operators).
+So the code is actively misleading, and the only reason someone would write
+this intentionally is to win an underhanded Rust contest or create a
+test-case for this lint.
+### Example
+
+if (x & 1 == 2) { }

src/docs/bad_bit_mask.md

@@ -0,0 +1,17 @@
+### What it does
+Checks for usage of `_.and_then(|x| Some(y))`, `_.and_then(|x| Ok(y))` or
+`_.or_else(|x| Err(y))`.
+### Why is this bad?
+Readability, this can be written more concisely as
+`_.map(|x| y)` or `_.map_err(|x| y)`.
+### Example
+
+let _ = opt().and_then(|s| Some(s.len()));
+let _ = res().and_then(|s| if s.len() == 42 { Ok(10) } else { Ok(20) });
+let _ = res().or_else(|s| if s.len() == 42 { Err(10) } else { Err(20) });
+
+The correct use would be:
+
+let _ = opt().map(|s| s.len());
+let _ = res().map(|s| if s.len() == 42 { 10 } else { 20 });
+let _ = res().map_err(|s| if s.len() == 42 { 10 } else { 20 });