Beautify more docs

src/bit_mask.rs

@@ -13,14 +13,14 @@ use utils::span_lint;
 /// 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               |
+/// |Comparison  |Bit Op |Example     |is always|Formula               |
-/// |------------|------|------------|---------|----------------------|
+/// |------------|-------|------------|---------|----------------------|
-/// |`==` or `!=`| `&`  |`x & 2 == 3`|`false`  |`c & m != c`          |
+/// |`==` or `!=`|  `&`  |`x & 2 == 3`|`false`  |`c & m != c`          |
-/// |`<`  or `>=`| `&`  |`x & 2 < 3` |`true`   |`m < c`               |
+/// |`<`  or `>=`|  `&`  |`x & 2 < 3` |`true`   |`m < c`               |
-/// |`>`  or `<=`| `&`  |`x & 1 > 1` |`false`  |`m <= c`              |
+/// |`>`  or `<=`|  `&`  |`x & 1 > 1` |`false`  |`m <= c`              |
-/// |`==` or `!=`| `|`  |`x | 1 == 0`|`false`  |`c | m != c`          |
+/// |`==` or `!=`|  `|`  |`x | 1 == 0`|`false`  |`c | m != c`          |
-/// |`<`  or `>=`| `|`  |`x | 1 < 1` |`false`  |`m >= c`              |
+/// |`<`  or `>=`|  `|`  |`x | 1 < 1` |`false`  |`m >= c`              |
-/// |`<=` or `>` | `|`  |`x | 1 > 0` |`true`   |`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).
 ///
@@ -38,7 +38,7 @@ declare_lint! {
 
 /// **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:
 ///
-/// |Comparison|Bit-Op   |Example    |equals |
+/// |Comparison| Bit Op  |Example    |equals |
 /// |----------|---------|-----------|-------|
 /// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`|
 /// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`|
@@ -61,21 +61,21 @@ declare_lint! {
 /// is one of {`&`, '|'} and `<cmp_op>` is one of {`!=`, `>=`, `>` ,
 /// `!=`, `>=`, `>`}) can be determined from the following table:
 ///
-/// |Comparison  |Bit-Op|Example     |is always|Formula               |
+/// |Comparison  |Bit Op |Example     |is always|Formula               |
-/// |------------|------|------------|---------|----------------------|
+/// |------------|-------|------------|---------|----------------------|
-/// |`==` or `!=`| `&`  |`x & 2 == 3`|`false`  |`c & m != c`          |
+/// |`==` or `!=`|  `&`  |`x & 2 == 3`|`false`  |`c & m != c`          |
-/// |`<`  or `>=`| `&`  |`x & 2 < 3` |`true`   |`m < c`               |
+/// |`<`  or `>=`|  `&`  |`x & 2 < 3` |`true`   |`m < c`               |
-/// |`>`  or `<=`| `&`  |`x & 1 > 1` |`false`  |`m <= c`              |
+/// |`>`  or `<=`|  `&`  |`x & 1 > 1` |`false`  |`m <= c`              |
-/// |`==` or `!=`| `|`  |`x | 1 == 0`|`false`  |`c | m != c`          |
+/// |`==` or `!=`|  `|`  |`x | 1 == 0`|`false`  |`c | m != c`          |
-/// |`<`  or `>=`| `|`  |`x | 1 < 1` |`false`  |`m >= c`              |
+/// |`<`  or `>=`|  `|`  |`x | 1 < 1` |`false`  |`m >= c`              |
-/// |`<=` or `>` | `|`  |`x | 1 > 0` |`true`   |`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|
+/// |Comparison| Bit Op  |Example    |equals |Formula|
 /// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`|`¹ && m <= c`|
 /// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`|`¹ && m < c` |
 ///

src/consts.rs

@@ -30,7 +30,7 @@ impl From<FloatTy> for FloatWidth {
     }
 }
 
-/// a Lit_-like enum to fold constant `Expr`s into
+/// A `LitKind`-like enum to fold constant `Expr`s into.
 #[derive(Debug, Clone)]
 pub enum Constant {
     /// a String "abc"

src/formatting.rs

@@ -82,7 +82,7 @@ impl EarlyLintPass for Formatting {
     }
 }
 
-/// Implementation of the SUSPICIOUS_ASSIGNMENT_FORMATTING lint.
+/// Implementation of the `SUSPICIOUS_ASSIGNMENT_FORMATTING` lint.
 fn check_assign(cx: &EarlyContext, expr: &ast::Expr) {
     if let ast::ExprKind::Assign(ref lhs, ref rhs) = expr.node {
         if !differing_macro_contexts(lhs.span, rhs.span) && !in_macro(cx, lhs.span) {
@@ -108,7 +108,7 @@ fn check_assign(cx: &EarlyContext, expr: &ast::Expr) {
     }
 }
 
-/// Implementation of the SUSPICIOUS_ELSE_FORMATTING lint for weird `else if`.
+/// Implementation of the `SUSPICIOUS_ELSE_FORMATTING` lint for weird `else if`.
 fn check_else_if(cx: &EarlyContext, expr: &ast::Expr) {
     if let Some((then, &Some(ref else_))) = unsugar_if(expr) {
         if unsugar_if(else_).is_some() && !differing_macro_contexts(then.span, else_.span) && !in_macro(cx, then.span) {

src/len_zero.rs

@@ -164,9 +164,9 @@ fn check_len_zero(cx: &LateContext, span: Span, name: &Name, args: &[P<Expr>], l
     }
 }
 
-/// check if this type has an is_empty method
+/// Check if this type has an `is_empty` method.
 fn has_is_empty(cx: &LateContext, expr: &Expr) -> bool {
-    /// get a ImplOrTraitItem and return true if it matches is_empty(self)
+    /// Get an `ImplOrTraitItem` and return true if it matches `is_empty(self)`.
     fn is_is_empty(cx: &LateContext, id: &ImplOrTraitItemId) -> bool {
         if let MethodTraitItemId(def_id) = *id {
             if let ty::MethodTraitItem(ref method) = cx.tcx.impl_or_trait_item(def_id) {
@@ -179,7 +179,7 @@ fn has_is_empty(cx: &LateContext, expr: &Expr) -> bool {
         }
     }
 
-    /// check the inherent impl's items for an is_empty(self) method
+    /// Check the inherent impl's items for an `is_empty(self)` method.
     fn has_is_empty_impl(cx: &LateContext, id: &DefId) -> bool {
         let impl_items = cx.tcx.impl_items.borrow();
         cx.tcx.inherent_impls.borrow().get(id).map_or(false, |ids| {

src/loops.rs

@@ -571,7 +571,7 @@ fn check_for_loop_explicit_counter(cx: &LateContext, arg: &Expr, body: &Expr, ex
     }
 }
 
-/// Check for the FOR_KV_MAP lint.
+/// Check for the `FOR_KV_MAP` lint.
 fn check_for_loop_over_map_kv(cx: &LateContext, pat: &Pat, arg: &Expr, body: &Expr, expr: &Expr) {
     if let PatKind::Tup(ref pat) = pat.node {
         if pat.len() == 2 {
@@ -607,7 +607,7 @@ fn check_for_loop_over_map_kv(cx: &LateContext, pat: &Pat, arg: &Expr, body: &Ex
 
 }
 
-/// Return true if the pattern is a `PatWild` or an ident prefixed with '_'.
+/// Return true if the pattern is a `PatWild` or an ident prefixed with `'_'`.
 fn pat_is_wild(pat: &PatKind, body: &Expr) -> bool {
     match *pat {
         PatKind::Wild => true,
@@ -750,8 +750,8 @@ impl<'v, 't> Visitor<'v> for VarUsedAfterLoopVisitor<'v, 't> {
 }
 
 
-/// Return true if the type of expr is one that provides IntoIterator impls
+/// Return true if the type of expr is one that provides `IntoIterator` impls
-/// for &T and &mut T, such as Vec.
+/// for `&T` and `&mut T`, such as `Vec`.
 #[cfg_attr(rustfmt, rustfmt_skip)]
 fn is_ref_iterable_type(cx: &LateContext, e: &Expr) -> bool {
     // no walk_ptrs_ty: calling iter() on a reference can make sense because it

src/matches.rs

@@ -330,7 +330,7 @@ fn check_match_ref_pats(cx: &LateContext, ex: &Expr, arms: &[Arm], source: Match
     }
 }
 
-/// Get all arms that are unbounded PatRange-s.
+/// Get all arms that are unbounded `PatRange`s.
 fn all_ranges(cx: &LateContext, arms: &[Arm]) -> Vec<SpannedRange<ConstVal>> {
     arms.iter()
         .filter_map(|arm| {

src/non_expressive_names.rs

@@ -251,7 +251,7 @@ impl EarlyLintPass for NonExpressiveNames {
     }
 }
 
-/// precondition: a_name.chars().count() < b_name.chars().count()
+/// Precondition: `a_name.chars().count() < b_name.chars().count()`.
 fn levenstein_not_1(a_name: &str, b_name: &str) -> bool {
     debug_assert!(a_name.chars().count() < b_name.chars().count());
     let mut a_chars = a_name.chars();

src/ptr_arg.rs

@@ -1,6 +1,4 @@
-//! Checks for usage of &Vec[_] and &String
+//! Checks for usage of  `&Vec[_]` and `&String`.
-//!
-//! This lint is **warn** by default
 
 use rustc::front::map::NodeItem;
 use rustc::lint::*;

src/strings.rs

@@ -1,4 +1,4 @@
-//! This LintPass catches both string addition and string addition + assignment
+//! This lint catches both string addition and string addition + assignment
 //!
 //! Note that since we have two lints where one subsumes the other, we try to
 //! disable the subsumed lint unless it has a higher level

src/utils/mod.rs

@@ -129,8 +129,8 @@ pub fn in_macro<T: LintContext>(cx: &T, span: Span) -> bool {
 /// Returns true if the macro that expanded the crate was outside of the current crate or was a
 /// compiler plugin.
 pub fn in_external_macro<T: LintContext>(cx: &T, span: Span) -> bool {
-    /// Invokes in_macro with the expansion info of the given span slightly heavy, try to use this
+    /// Invokes `in_macro` with the expansion info of the given span slightly heavy, try to use
-    /// after other checks have already happened.
+    /// this after other checks have already happened.
     fn in_macro_ext<T: LintContext>(cx: &T, opt_info: Option<&ExpnInfo>) -> bool {
         // no ExpnInfo = no macro
         opt_info.map_or(false, |info| {
@@ -657,7 +657,7 @@ pub fn is_direct_expn_of(cx: &LateContext, span: Span, name: &str) -> Option<Spa
     }
 }
 
-/// Returns index of character after first CamelCase component of `s`
+/// Return the index of the character after the first camel-case component of `s`.
 pub fn camel_case_until(s: &str) -> usize {
     let mut iter = s.char_indices();
     if let Some((_, first)) = iter.next() {
@@ -690,7 +690,7 @@ pub fn camel_case_until(s: &str) -> usize {
     }
 }
 
-/// Returns index of last CamelCase component of `s`.
+/// Return index of the last camel-case component of `s`.
 pub fn camel_case_from(s: &str) -> usize {
     let mut iter = s.char_indices().rev();
     if let Some((_, first)) = iter.next() {
@@ -719,7 +719,7 @@ pub fn camel_case_from(s: &str) -> usize {
     last_i
 }
 
-/// Represents a range akin to `ast::ExprKind::Range`.
+/// Represent a range akin to `ast::ExprKind::Range`.
 #[derive(Debug, Copy, Clone)]
 pub struct UnsugaredRange<'a> {
     pub start: Option<&'a Expr>,

src/zero_div_zero.rs

@@ -4,7 +4,7 @@ use rustc_front::hir::*;
 use utils::span_help_and_lint;
 
 /// `ZeroDivZeroPass` is a pass that checks for a binary expression that consists
-/// `of 0.0/0.0`, which is always NaN. It is more clear to replace instances of
+/// `of 0.0/0.0`, which is always `NaN`. It is more clear to replace instances of
 /// `0.0/0.0` with `std::f32::NaN` or `std::f64::NaN`, depending on the precision.
 pub struct ZeroDivZeroPass;
 

tests/compile-fail/methods.rs

@@ -85,8 +85,8 @@ macro_rules! opt_map {
 }
 
 /// Checks implementation of the following lints:
-/// OPTION_MAP_UNWRAP_OR
+/// * `OPTION_MAP_UNWRAP_OR`
-/// OPTION_MAP_UNWRAP_OR_ELSE
+/// * `OPTION_MAP_UNWRAP_OR_ELSE`
 fn option_methods() {
     let opt = Some(1);
 
@@ -154,7 +154,7 @@ impl IteratorFalsePositives {
     }
 }
 
-/// Checks implementation of FILTER_NEXT lint
+/// Checks implementation of `FILTER_NEXT` lint
 fn filter_next() {
     let v = vec![3, 2, 1, 0, -1, -2, -3];
 
@@ -174,7 +174,7 @@ fn filter_next() {
     let _ = foo.filter().next();
 }
 
-/// Checks implementation of SEARCH_IS_SOME lint
+/// Checks implementation of `SEARCH_IS_SOME` lint
 fn search_is_some() {
     let v = vec![3, 2, 1, 0, -1, -2, -3];
 
@@ -218,7 +218,7 @@ fn search_is_some() {
     let _ = foo.rposition().is_some();
 }
 
-/// Checks implementation of the OR_FUN_CALL lint
+/// Checks implementation of the `OR_FUN_CALL` lint
 fn or_fun_call() {
     struct Foo;
 

tests/used_underscore_binding_macro.rs

@@ -3,7 +3,7 @@
 
 extern crate rustc_serialize;
 
-/// Test that we do not lint for unused underscores in a MacroAttribute expansion
+/// Test that we do not lint for unused underscores in a `MacroAttribute` expansion
 #[deny(used_underscore_binding)]
 #[derive(RustcEncodable)]
 struct MacroAttributesTest {