more doc comments

src/block_in_if_condition.rs

@@ -3,11 +3,25 @@ use rustc::lint::{LateLintPass, LateContext, LintArray, LintPass};
 use rustc_front::intravisit::{Visitor, walk_expr};
 use utils::*;
 
+/// **What it does:** This lint 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.
+///
+/// **Known problems:** None
+///
+/// **Example:** `if { true } ..`
 declare_lint! {
     pub BLOCK_IN_IF_CONDITION_EXPR, Warn,
     "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.
+///
+/// **Why is this bad?** Using blocks in the condition makes it hard to read.
+///
+/// **Known problems:** None
+///
+/// **Example:** `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 \

src/map_clone.rs

@@ -4,6 +4,13 @@ use utils::{CLONE_PATH, OPTION_PATH};
 use utils::{is_adjusted, match_path, match_trait_method, match_type, snippet, span_help_and_lint};
 use utils::{walk_ptrs_ty, walk_ptrs_ty_depth};
 
+/// **What it does:** This lint checks for mapping clone() over an iterator. It is `Warn` by default and suggests to use `.cloned()` instead.
+///
+/// **Why is this bad?** It makes the code less readable.
+///
+/// **Known problems:** False negative: The lint currently misses mapping `Clone::clone` directly. Issue #436 is tracking this.
+///
+/// **Example:** `x.map(|e| e.clone());`
 declare_lint!(pub MAP_CLONE, Warn,
               "using `.map(|x| x.clone())` to clone an iterator or option's contents (recommends \
               `.cloned()` instead)");