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)]