Improve docs

Author: mcarton

clippy_lints/src/approx_const.rs

@@ -10,7 +10,10 @@ use utils::span_lint;
 ///
 /// **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:** `let x = 3.14;`
+/// **Example:**
+/// ```rust
+/// let x = 3.14;
+/// ```
 declare_lint! {
     pub APPROX_CONSTANT,
     Warn,

clippy_lints/src/arithmetic.rs

@@ -12,7 +12,7 @@ use utils::span_lint;
 /// **Known problems:** None
 ///
 /// **Example:**
-/// ```
+/// ```rust
 /// a + 1
 /// ```
 declare_restriction_lint! {
@@ -28,7 +28,7 @@ declare_restriction_lint! {
 /// **Known problems:** None
 ///
 /// **Example:**
-/// ```
+/// ```rust
 /// a + 1.0
 /// ```
 declare_restriction_lint! {

clippy_lints/src/array_indexing.rs

@@ -16,7 +16,7 @@ use utils::{self, higher};
 ///
 /// **Example:**
 ///
-/// ```
+/// ```rust
 /// let x = [1,2,3,4];
 /// ...
 /// x[9];
@@ -38,7 +38,7 @@ declare_lint! {
 ///
 /// **Example:**
 ///
-/// ```
+/// ```rust
 /// ...
 /// x[2];
 /// &x[0..2];

clippy_lints/src/assign_ops.rs

@@ -11,7 +11,7 @@ use utils::{higher, sugg};
 /// **Known problems:** Types implementing `OpAssign` don't necessarily implement `Op`.
 ///
 /// **Example:**
-/// ```
+/// ```rust
 /// a += 1;
 /// ```
 declare_restriction_lint! {
@@ -27,7 +27,7 @@ declare_restriction_lint! {
 ///
 /// **Example:**
 ///
-/// ```
+/// ```rust
 /// let mut a = 5;
 /// ...
 /// a = a + b;

clippy_lints/src/attrs.rs

@@ -18,7 +18,7 @@ use utils::paths;
 /// **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
 /// #[inline(always)]
 /// fn not_quite_hot_code(..) { ... }
 /// ```
@@ -34,7 +34,7 @@ declare_lint! {
 /// **Known problems:** None
 ///
 /// **Example:**
-/// ```
+/// ```rust
 /// #[deprecated(since = "forever")]
 /// fn something_else(..) { ... }
 /// ```

clippy_lints/src/bit_mask.rs

@@ -26,7 +26,10 @@ use utils::span_lint;
 ///
 /// **Known problems:** None
 ///
-/// **Example:** `x & 1 == 2` (also see table above)
+/// **Example:**
+/// ```rust
+/// if (x & 1 == 2) { … }
+/// ```
 declare_lint! {
     pub BAD_BIT_MASK,
     Warn,
@@ -45,7 +48,10 @@ declare_lint! {
 ///
 /// **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:** `x | 1 > 3` (also see table above)
+/// **Example:**
+/// ```rust
+/// if (x | 1 > 3) { … }
+/// ```
 declare_lint! {
     pub INEFFECTIVE_BIT_MASK,
     Warn,

clippy_lints/src/blacklisted_name.rs

@@ -8,7 +8,10 @@ use utils::span_lint;
 ///
 /// **Known problems:** None.
 ///
-/// **Example:** `let foo = 3.14;`
+/// **Example:**
+/// ```rust
+/// let foo = 3.14;
+/// ```
 declare_lint! {
     pub BLACKLISTED_NAME,
     Warn,

clippy_lints/src/block_in_if_condition.rs

@@ -9,7 +9,10 @@ use utils::*;
 ///
 /// **Known problems:** None
 ///
-/// **Example:** `if { true } ..`
+/// **Example:**
+/// ```rust
+/// if { true } ..
+/// ```
 declare_lint! {
     pub BLOCK_IN_IF_CONDITION_EXPR, Warn,
     "braces can be eliminated in conditions that are expressions, e.g `if { true } ...`"
@@ -21,7 +24,12 @@ declare_lint! {
 ///
 /// **Known problems:** None
 ///
-/// **Example:** `if { let x = somefunc(); x } ..` or `if somefunc(|x| { x == 47 }) ..`
+/// **Example:**
+/// ```rust
+/// if { let x = somefunc(); x } ..
+/// // or
+/// if somefunc(|x| { x == 47 }) ..
+/// ```
 declare_lint! {
     pub BLOCK_IN_IF_CONDITION_STMT, Warn,
     "avoid complex blocks in conditions, instead move the block higher and bind it \

clippy_lints/src/booleans.rs

@@ -6,23 +6,23 @@ use syntax::codemap::{DUMMY_SP, dummy_spanned};
 use syntax::util::ThinVec;
 use utils::{span_lint_and_then, in_macro, snippet_opt, SpanlessEq};
 
-/// **What it does:** This lint checks for boolean expressions that can be written more concisely
+/// **What it does:** This lint checks for boolean expressions that can be written more concisely.
 ///
-/// **Why is this bad?** Readability of boolean expressions suffers from unnecesessary duplication
+/// **Why is this bad?** Readability of boolean expressions suffers from unnecessary duplication.
 ///
-/// **Known problems:** Ignores short circuting behavior of `||` and `&&`. Ignores `|`, `&` and `^`.
+/// **Known problems:** Ignores short circuiting behavior of `||` and `&&`. Ignores `|`, `&` and `^`.
 ///
 /// **Example:** `if a && true` should be `if a` and `!(a == b)` should be `a != b`
 declare_lint! {
     pub NONMINIMAL_BOOL, Allow,
     "checks for boolean expressions that can be written more concisely"
 }
 
-/// **What it does:** This lint checks for boolean expressions that contain terminals that can be eliminated
+/// **What it does:** This lint checks for boolean expressions that contain terminals that can be eliminated.
 ///
-/// **Why is this bad?** This is most likely a logic bug
+/// **Why is this bad?** This is most likely a logic bug.
 ///
-/// **Known problems:** Ignores short circuiting behavior
+/// **Known problems:** Ignores short circuiting behavior.
 ///
 /// **Example:** The `b` in `if a && b || a` is unnecessary because the expression is equivalent to `if a`
 declare_lint! {

clippy_lints/src/collapsible_if.rs

@@ -26,14 +26,44 @@ use utils::sugg::Sugg;
 ///
 /// **Known problems:** None
 ///
-/// **Example:** `if x { if y { .. } }`
+/// **Example:**
+/// ```rust
+/// if x {
+///     if y {
+///         …
+///     }
+/// }
+///
+/// // or
+///
+/// if x {
+///     …
+/// } else {
+///     if y {
+///         …
+///     }
+/// }
+/// ```
+///
+/// Should be written:
+///
+/// ```rust
+/// if x && y {
+///     …
+/// }
+///
+/// // or
+///
+/// if x {
+///     …
+/// } else if y {
+///     …
+/// }
+/// ```
 declare_lint! {
     pub COLLAPSIBLE_IF,
     Warn,
-    "two nested `if`-expressions can be collapsed into one, e.g. `if x { if y { foo() } }` \
-     can be written as `if x && y { foo() }` \
-     and an `else { if .. }` expression can be collapsed to \
-     `else if`"
+    "`if`s that can be collapsed (e.g. `if x { if y { … } }` and `else { if x { … } }`)"
 }
 
 #[derive(Copy,Clone)]

clippy_lints/src/copies.rs

@@ -8,28 +8,51 @@ use syntax::util::small_vector::SmallVector;
 use utils::{SpanlessEq, SpanlessHash};
 use utils::{get_parent_expr, in_macro, span_lint_and_then, span_note_and_lint, snippet};
 
-/// **What it does:** This lint checks for consecutive `ifs` with the same condition. This lint is
-/// `Warn` by default.
+/// **What it does:** This lint checks for consecutive `ifs` with the same condition.
 ///
 /// **Why is this bad?** This is probably a copy & paste error.
 ///
 /// **Known problems:** Hopefully none.
 ///
-/// **Example:** `if a == b { .. } else if a == b { .. }`
+/// **Example:**
+/// ```rust
+/// if a == b {
+///     …
+/// } else if a == b {
+///     …
+/// }
+/// ```
+///
+/// Note that this lint ignores all conditions with a function call as it could have side effects:
+///
+/// ```rust
+/// if foo() {
+///     …
+/// } else if foo() { // not linted
+///     …
+/// }
+/// ```
 declare_lint! {
     pub IFS_SAME_COND,
     Warn,
     "consecutive `ifs` with the same condition"
 }
 
 /// **What it does:** This lint checks for `if/else` with the same body as the *then* part and the
-/// *else* part. This lint is `Warn` by default.
+/// *else* part.
 ///
 /// **Why is this bad?** This is probably a copy & paste error.
 ///
 /// **Known problems:** Hopefully none.
 ///
-/// **Example:** `if .. { 42 } else { 42 }`
+/// **Example:**
+/// ```rust
+/// let foo = if … {
+///     42
+/// } else {
+///     42
+/// };
+/// ```
 declare_lint! {
     pub IF_SAME_THEN_ELSE,
     Warn,

clippy_lints/src/enum_clike.rs

@@ -6,13 +6,22 @@ use rustc_const_math::*;
 use rustc::hir::*;
 use utils::span_lint;
 
-/// **What it does:** Lints on C-like enums that are `repr(isize/usize)` and have values that don't fit into an `i32`.
+/// **What it does:** Lints on C-like enumerations that are `repr(isize/usize)` and have values
+/// that don't fit into an `i32`.
 ///
-/// **Why is this bad?** This will truncate the variant value on 32bit architectures, but works fine on 64 bit.
+/// **Why is this bad?** This will truncate the variant value on 32 bit architectures, but works
+/// fine on 64 bit.
 ///
 /// **Known problems:** None
 ///
-/// **Example:** `#[repr(usize)] enum NonPortable { X = 0x1_0000_0000, Y = 0 }`
+/// **Example:**
+/// ```rust
+/// #[repr(usize)]
+/// enum NonPortable {
+///     X = 0x1_0000_0000,
+///     Y = 0
+/// }
+/// ```
 declare_lint! {
     pub ENUM_CLIKE_UNPORTABLE_VARIANT, Warn,
     "finds C-like enums that are `repr(isize/usize)` and have values that don't fit into an `i32`"

clippy_lints/src/enum_glob_use.rs

@@ -9,13 +9,16 @@ use syntax::ast::NodeId;
 use syntax::codemap::Span;
 use utils::span_lint;
 
-/// **What it does:** Warns when `use`ing all variants of an enum
+/// **What it does:** Warns when `use`ing all variants of an enumeration.
 ///
-/// **Why is this bad?** It is usually better style to use the prefixed name of an enum variant, rather than importing variants
+/// **Why is this bad?** It is usually better style to use the prefixed name of an enumeration variant, rather than importing variants
 ///
-/// **Known problems:** Old-style enums that prefix the variants are still around
+/// **Known problems:** Old-style enumerations that prefix the variants are still around
 ///
-/// **Example:** `use std::cmp::Ordering::*;`
+/// **Example:**
+/// ```rust
+/// use std::cmp::Ordering::*;
+/// ```
 declare_lint! { pub ENUM_GLOB_USE, Allow,
     "finds use items that import all variants of an enum" }
 

clippy_lints/src/enum_variants.rs

@@ -7,13 +7,21 @@ use syntax::parse::token::InternedString;
 use utils::{span_help_and_lint, span_lint};
 use utils::{camel_case_from, camel_case_until, in_macro};
 
-/// **What it does:** Warns on enum variants that are prefixed or suffixed by the same characters
+/// **What it does:** Warns on enumeration variants that are prefixed or suffixed by the same
+/// characters.
 ///
-/// **Why is this bad?** Enum variant names should specify their variant, not the enum, too.
+/// **Why is this bad?** Enumeration variant names should specify their variant, not repeat the
+/// enumeration name.
 ///
 /// **Known problems:** None
 ///
-/// **Example:** enum Cake { BlackForestCake, HummingbirdCake }
+/// **Example:**
+/// ```rust
+/// enum Cake {
+///     BlackForestCake,
+///     HummingbirdCake,
+/// }
+/// ```
 declare_lint! {
     pub ENUM_VARIANT_NAMES, Warn,
     "finds enums where all variants share a prefix/postfix"
@@ -25,7 +33,12 @@ declare_lint! {
 ///
 /// **Known problems:** None
 ///
-/// **Example:** mod cake { struct BlackForestCake; }
+/// **Example:**
+/// ```rust
+/// mod cake {
+///     struct BlackForestCake;
+/// }
+/// ```
 declare_lint! {
     pub STUTTER, Allow,
     "finds type names prefixed/postfixed with their containing module's name"

clippy_lints/src/eq_op.rs

@@ -8,9 +8,15 @@ use utils::{SpanlessEq, span_lint};
 ///
 /// **Why is this bad?** This is usually just a typo or a copy and paste error.
 ///
-/// **Known problems:** False negatives: We had some false positives regarding calls (notably [racer](https://github.com/phildawes/racer) had one instance of `x.pop() && x.pop()`), so we removed matching any function or method calls. We may introduce a whitelist of known pure functions in the future.
+/// **Known problems:** False negatives: We had some false positives regarding calls (notably
+/// [racer](https://github.com/phildawes/racer) had one instance of `x.pop() && x.pop()`), so we
+/// removed matching any function or method calls. We may introduce a whitelist of known pure
+/// functions in the future.
 ///
-/// **Example:** `x + 1 == x + 1`
+/// **Example:**
+/// ```rust
+/// x + 1 == x + 1
+/// ```
 declare_lint! {
     pub EQ_OP,
     Warn,

clippy_lints/src/escape.rs

@@ -19,7 +19,8 @@ pub struct Pass {
 
 /// **What it does:** This lint checks for usage of `Box<T>` where an unboxed `T` would work fine.
 ///
-/// **Why is this bad?** This is an unnecessary allocation, and bad for performance. It is only necessary to allocate if you wish to move the box into something.
+/// **Why is this bad?** This is an unnecessary allocation, and bad for performance. It is only
+/// necessary to allocate if you wish to move the box into something.
 ///
 /// **Known problems:** None
 ///