Some housekeeping on lint descriptions

CONTRIBUTING.md

@@ -42,13 +42,16 @@ travis build actually checks for this.
 
 Also please document your lint with a doc comment akin to the following:
 ```rust
-/// **What it does:** Describe what the lint matches.
+/// **What it does:** Checks for ... (describe what the lint matches).
 ///
-/// **Why is this bad?** Write the reason for linting the code.
+/// **Why is this bad?** Supply the reason for linting the code.
 ///
-/// **Known problems:** Hopefully none.
+/// **Known problems:** None. (Or describe where it could go wrong.)
 ///
-/// **Example:** Insert a short example if you have one
+/// **Example:**
+/// ```rust
+/// Insert a short example if you have one.
+/// ```
 ```
 
 Our `util/update_wiki.py` script can then add your lint docs to the wiki.

clippy_lints/src/approx_const.rs

@@ -4,11 +4,22 @@ use std::f64::consts as f64;
 use syntax::ast::{Lit, LitKind, FloatTy};
 use utils::span_lint;
 
-/// **What it does:** This lint 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.
+/// **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).
+/// **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).
 ///
-/// **Known problems:** If you happen to have a value that is within 1/8192 of a known constant, but is not *and should not* be the same, this lint will report your value anyway. We have not yet noticed any false positives in code we tested clippy with (this includes servo), but YMMV.
+/// **Known problems:** If you happen to have a value that is within 1/8192 of a
+/// known constant, but is not *and should not* be the same, this lint will
+/// report your value anyway. We have not yet noticed any false positives in
+/// code we tested clippy with (this includes servo), but YMMV.
 ///
 /// **Example:**
 /// ```rust
@@ -72,7 +83,8 @@ fn check_known_consts(cx: &LateContext, e: &Expr, s: &str, module: &str) {
                 span_lint(cx,
                           APPROX_CONSTANT,
                           e.span,
-                          &format!("approximate value of `{}::consts::{}` found. Consider using it directly", module, &name));
+                          &format!("approximate value of `{}::consts::{}` found. \
+                                    Consider using it directly", module, &name));
                 return;
             }
         }

clippy_lints/src/arithmetic.rs

@@ -3,13 +3,13 @@ use rustc::lint::*;
 use syntax::codemap::Span;
 use utils::span_lint;
 
-/// **What it does:** This lint checks for plain integer arithmetic
+/// **What it does:** Checks for plain integer arithmetic.
 ///
 /// **Why is this bad?** This is only checked against overflow in debug builds.
 /// In some applications one wants explicitly checked, wrapping or saturating
 /// arithmetic.
 ///
-/// **Known problems:** None
+/// **Known problems:** None.
 ///
 /// **Example:**
 /// ```rust
@@ -20,12 +20,12 @@ declare_restriction_lint! {
     "Any integer arithmetic statement"
 }
 
-/// **What it does:** This lint checks for float arithmetic
+/// **What it does:** Checks for float arithmetic.
 ///
 /// **Why is this bad?** For some embedded systems or kernel development, it
-/// can be useful to rule out floating-point numbers
+/// can be useful to rule out floating-point numbers.
 ///
-/// **Known problems:** None
+/// **Known problems:** None.
 ///
 /// **Example:**
 /// ```rust

clippy_lints/src/array_indexing.rs

@@ -8,14 +8,13 @@ use rustc::hir::*;
 use syntax::ast::RangeLimits;
 use utils::{self, higher};
 
-/// **What it does:** Check for out of bounds array indexing with a constant index.
+/// **What it does:** Checks for out of bounds array indexing with a constant index.
 ///
 /// **Why is this bad?** This will always panic at runtime.
 ///
 /// **Known problems:** Hopefully none.
 ///
 /// **Example:**
-///
 /// ```rust
 /// let x = [1,2,3,4];
 /// ...
@@ -28,16 +27,15 @@ declare_lint! {
     "out of bound constant indexing"
 }
 
-/// **What it does:** Check for usage of indexing or slicing.
+/// **What it does:** Checks for usage of indexing or slicing.
 ///
-/// **Why is this bad?** Usually, this can be safely allowed. However,
-/// in some domains such as kernel development, a panic can cause the
-/// whole operating system to crash.
+/// **Why is this bad?** Usually, this can be safely allowed. However, in some
+/// domains such as kernel development, a panic can cause the whole operating
+/// system to crash.
 ///
 /// **Known problems:** Hopefully none.
 ///
 /// **Example:**
-///
 /// ```rust
 /// ...
 /// x[2];

clippy_lints/src/assign_ops.rs

@@ -3,10 +3,10 @@ use rustc::lint::*;
 use utils::{span_lint_and_then, snippet_opt, SpanlessEq, get_trait_def_id, implements_trait};
 use utils::{higher, sugg};
 
-/// **What it does:** This lint checks for `+=` operations and similar.
+/// **What it does:** Checks for compound assignment operations (`+=` and similar).
 ///
-/// **Why is this bad?** Projects with many developers from languages without those operations may
-/// find them unreadable and not worth their weight.
+/// **Why is this bad?** Projects with many developers from languages without
+/// those operations may find them unreadable and not worth their weight.
 ///
 /// **Known problems:** Types implementing `OpAssign` don't necessarily implement `Op`.
 ///
@@ -19,14 +19,14 @@ declare_restriction_lint! {
     "any assignment operation"
 }
 
-/// **What it does:** Check for `a = a op b` or `a = b commutative_op a` patterns.
+/// **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.
+/// **Known problems:** While forbidden by the spec, `OpAssign` traits may have
+/// implementations that differ from the regular `Op` impl.
 ///
 /// **Example:**
-///
 /// ```rust
 /// let mut a = 5;
 /// ...
@@ -38,14 +38,14 @@ declare_lint! {
     "assigning the result of an operation on a variable to that same variable"
 }
 
-/// **What it does:** Check for `a op= a op b` or `a op= b op a` patterns.
+/// **What it does:** Checks for `a op= a op b` or `a op= b op a` patterns.
 ///
-/// **Why is this bad?** Most likely these are bugs where one meant to write `a op= b`
+/// **Why is this bad?** Most likely these are bugs where one meant to write `a op= b`.
 ///
-/// **Known problems:** Someone might actually mean `a op= a op b`, but that should rather be written as `a = (2 * a) op b` where applicable.
+/// **Known problems:** Someone might actually mean `a op= a op b`, but that
+/// should rather be written as `a = (2 * a) op b` where applicable.
 ///
 /// **Example:**
-///
 /// ```rust
 /// let mut a = 5;
 /// ...

clippy_lints/src/attrs.rs

@@ -9,13 +9,20 @@ use syntax::codemap::Span;
 use utils::{in_macro, match_path, span_lint};
 use utils::paths;
 
-/// **What it does:** This lint checks for items annotated with `#[inline(always)]`, unless the annotated function is empty or simply panics.
+/// **What it does:** Checks for items annotated with `#[inline(always)]`,
+/// unless the annotated function is empty or simply panics.
 ///
-/// **Why is this bad?** While there are valid uses of this annotation (and once you know when to use it, by all means `allow` this lint), it's a common newbie-mistake to pepper one's code with it.
+/// **Why is this bad?** While there are valid uses of this annotation (and once
+/// you know when to use it, by all means `allow` this lint), it's a common
+/// newbie-mistake to pepper one's code with it.
 ///
-/// As a rule of thumb, before slapping `#[inline(always)]` on a function, measure if that additional function call really affects your runtime profile sufficiently to make up for the increase in compile time.
+/// As a rule of thumb, before slapping `#[inline(always)]` on a function,
+/// measure if that additional function call really affects your runtime profile
+/// sufficiently to make up for the increase in compile time.
 ///
-/// **Known problems:** False positives, big time. This lint is meant to be deactivated by everyone doing serious performance work. This means having done the measurement.
+/// **Known problems:** False positives, big time. This lint is meant to be
+/// deactivated by everyone doing serious performance work. This means having
+/// done the measurement.
 ///
 /// **Example:**
 /// ```rust
@@ -27,11 +34,13 @@ declare_lint! {
     "`#[inline(always)]` is a bad idea in most cases"
 }
 
-/// **What it does:** This lint checks for `#[deprecated]` annotations with a `since` field that is not a valid semantic version..
+/// **What it does:** Checks for `#[deprecated]` annotations with a `since`
+/// field that is not a valid semantic version.
 ///
-/// **Why is this bad?** For checking the version of the deprecation, it must be valid semver. Failing that, the contained information is useless.
+/// **Why is this bad?** For checking the version of the deprecation, it must be
+/// a valid semver. Failing that, the contained information is useless.
 ///
-/// **Known problems:** None
+/// **Known problems:** None.
 ///
 /// **Example:**
 /// ```rust

clippy_lints/src/bit_mask.rs

@@ -6,10 +6,12 @@ use syntax::ast::LitKind;
 use syntax::codemap::Span;
 use utils::span_lint;
 
-/// **What it does:** This lint checks for incompatible bit masks in comparisons.
+/// **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:
+/// 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               |
 /// |------------|------|------------|---------|----------------------|
@@ -20,11 +22,15 @@ use utils::span_lint;
 /// |`<`  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).
+/// **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.
+/// 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.
 ///
-/// **Known problems:** None
+/// **Known problems:** None.
 ///
 /// **Example:**
 /// ```rust
@@ -37,16 +43,23 @@ declare_lint! {
      (because in the example `select` containing bits that `mask` doesn't have)"
 }
 
-/// **What it does:** This lint checks for bit masks in comparisons which can be removed without changing the outcome. The basic structure can be seen in the following table:
+/// **What it does:** Checks for bit masks in comparisons which can be removed
+/// without changing the outcome. The basic structure can be seen in the
+/// following table:
 ///
 /// |Comparison| Bit Op  |Example    |equals |
 /// |----------|---------|-----------|-------|
 /// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`|
 /// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`|
 ///
-/// **Why is this bad?** Not equally evil as [`bad_bit_mask`](#bad_bit_mask), but still a bit misleading, because the bit mask is ineffective.
+/// **Why is this bad?** Not equally evil as [`bad_bit_mask`](#bad_bit_mask),
+/// but still a bit misleading, because the bit mask is ineffective.
 ///
-/// **Known problems:** False negatives: This lint will only match instances where we have figured out the math (which is for a power-of-two compared value). This means things like `x | 1 >= 7` (which would be better written as `x >= 6`) will not be reported (but bit masks like this are fairly uncommon).
+/// **Known problems:** False negatives: This lint will only match instances
+/// where we have figured out the math (which is for a power-of-two compared
+/// value). This means things like `x | 1 >= 7` (which would be better written
+/// as `x >= 6`) will not be reported (but bit masks like this are fairly
+/// uncommon).
 ///
 /// **Example:**
 /// ```rust
@@ -58,32 +71,6 @@ declare_lint! {
     "expressions where a bit mask will be rendered useless by a comparison, e.g. `(x | 1) > 2`"
 }
 
-/// Checks for incompatible bit masks in comparisons, e.g. `x & 1 == 2`.
-/// This cannot work because the bit that makes up the value two was
-/// zeroed out by the bit-and with 1. So 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`               |
-///
-/// This lint is **deny** by default
-///
-/// There is also a lint that warns on ineffective masks that is *warn*
-/// by default.
-///
-/// |Comparison|Bit Op   |Example    |equals |Formula|
-/// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`|`¹ && m <= c`|
-/// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`|`¹ && m < c` |
-///
-/// `¹ power_of_two(c + 1)`
 #[derive(Copy,Clone)]
 pub struct BitMask;
 

clippy_lints/src/blacklisted_name.rs

@@ -2,9 +2,11 @@ use rustc::lint::*;
 use rustc::hir::*;
 use utils::span_lint;
 
-/// **What it does:** This lints about usage of blacklisted names.
+/// **What it does:** Checks for usage of blacklisted names for variables, such
+/// as `foo`.
 ///
-/// **Why is this bad?** These names are usually placeholder names and should be avoided.
+/// **Why is this bad?** These names are usually placeholder names and should be
+/// avoided.
 ///
 /// **Known problems:** None.
 ///

clippy_lints/src/block_in_if_condition.rs

@@ -3,11 +3,13 @@ use rustc::hir::*;
 use rustc::hir::intravisit::{Visitor, walk_expr};
 use utils::*;
 
-/// **What it does:** This lint checks for `if` conditions that use blocks to contain an expression.
+/// **What it does:** Checks for `if` conditions that use blocks to contain an
+/// expression.
 ///
-/// **Why is this bad?** It isn't really rust style, same as using parentheses to contain expressions.
+/// **Why is this bad?** It isn't really Rust style, same as using parentheses
+/// to contain expressions.
 ///
-/// **Known problems:** None
+/// **Known problems:** None.
 ///
 /// **Example:**
 /// ```rust
@@ -18,11 +20,12 @@ declare_lint! {
     "braces can be eliminated in conditions that are expressions, e.g `if { true } ...`"
 }
 
-/// **What it does:** This lint checks for `if` conditions that use blocks containing statements, or conditions that use closures with blocks.
+/// **What it does:** Checks for `if` conditions that use blocks containing
+/// statements, or conditions that use closures with blocks.
 ///
 /// **Why is this bad?** Using blocks in the condition makes it hard to read.
 ///
-/// **Known problems:** None
+/// **Known problems:** None.
 ///
 /// **Example:**
 /// ```rust