From 941ec6e4f5cfc54078f5fe65702ec46b6c59b8d2 Mon Sep 17 00:00:00 2001 From: mcarton Date: Sat, 19 Mar 2016 17:48:29 +0100 Subject: [PATCH] Beautify more docs --- src/bit_mask.rs | 36 +++++++++++++------------- src/consts.rs | 2 +- src/formatting.rs | 4 +-- src/len_zero.rs | 6 ++--- src/loops.rs | 8 +++--- src/matches.rs | 2 +- src/non_expressive_names.rs | 2 +- src/ptr_arg.rs | 4 +-- src/strings.rs | 2 +- src/utils/mod.rs | 10 +++---- src/zero_div_zero.rs | 2 +- tests/compile-fail/methods.rs | 10 +++---- tests/used_underscore_binding_macro.rs | 2 +- 13 files changed, 44 insertions(+), 46 deletions(-) diff --git a/src/bit_mask.rs b/src/bit_mask.rs index f96927f15484..15fbabf9f0b3 100644 --- a/src/bit_mask.rs +++ b/src/bit_mask.rs @@ -13,14 +13,14 @@ use utils::span_lint; /// The formula for detecting if an expression of the type `_ m c` (where `` /// is one of {`&`, `|`} and `` 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` | +/// |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` | /// /// **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 `` 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` | +/// |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| +/// |Comparison| Bit Op |Example |equals |Formula| /// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`|`¹ && m <= c`| /// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`|`¹ && m < c` | /// diff --git a/src/consts.rs b/src/consts.rs index 67da1216c42f..97a99dda4b5b 100644 --- a/src/consts.rs +++ b/src/consts.rs @@ -30,7 +30,7 @@ impl From 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" diff --git a/src/formatting.rs b/src/formatting.rs index 091280de28da..aa6dd46cf0b9 100644 --- a/src/formatting.rs +++ b/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) { diff --git a/src/len_zero.rs b/src/len_zero.rs index 6dad8684354e..1a097820e1e3 100644 --- a/src/len_zero.rs +++ b/src/len_zero.rs @@ -164,9 +164,9 @@ fn check_len_zero(cx: &LateContext, span: Span, name: &Name, args: &[P], 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| { diff --git a/src/loops.rs b/src/loops.rs index c0d3993746a0..546f07a65075 100644 --- a/src/loops.rs +++ b/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 -/// for &T and &mut T, such as Vec. +/// Return true if the type of expr is one that provides `IntoIterator` impls +/// 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 diff --git a/src/matches.rs b/src/matches.rs index bc3b45b32ef5..7bffd445f6b9 100644 --- a/src/matches.rs +++ b/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> { arms.iter() .filter_map(|arm| { diff --git a/src/non_expressive_names.rs b/src/non_expressive_names.rs index b7d2ac80a10f..d7cb6fc5d281 100644 --- a/src/non_expressive_names.rs +++ b/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(); diff --git a/src/ptr_arg.rs b/src/ptr_arg.rs index b7882bfda16d..6498db66e139 100644 --- a/src/ptr_arg.rs +++ b/src/ptr_arg.rs @@ -1,6 +1,4 @@ -//! Checks for usage of &Vec[_] and &String -//! -//! This lint is **warn** by default +//! Checks for usage of `&Vec[_]` and `&String`. use rustc::front::map::NodeItem; use rustc::lint::*; diff --git a/src/strings.rs b/src/strings.rs index aa9cdcce50cb..9f68175b2024 100644 --- a/src/strings.rs +++ b/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 diff --git a/src/utils/mod.rs b/src/utils/mod.rs index 017890dc4610..34404f4c2e98 100644 --- a/src/utils/mod.rs +++ b/src/utils/mod.rs @@ -129,8 +129,8 @@ pub fn in_macro(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(cx: &T, span: Span) -> bool { - /// Invokes in_macro with the expansion info of the given span slightly heavy, try to use this - /// after other checks have already happened. + /// Invokes `in_macro` with the expansion info of the given span slightly heavy, try to use + /// this after other checks have already happened. fn in_macro_ext(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 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>, diff --git a/src/zero_div_zero.rs b/src/zero_div_zero.rs index 1d119b051762..f58b0e695a91 100644 --- a/src/zero_div_zero.rs +++ b/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; diff --git a/tests/compile-fail/methods.rs b/tests/compile-fail/methods.rs index 74f262b05a78..9d938ebb19e6 100644 --- a/tests/compile-fail/methods.rs +++ b/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_ELSE +/// * `OPTION_MAP_UNWRAP_OR` +/// * `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; diff --git a/tests/used_underscore_binding_macro.rs b/tests/used_underscore_binding_macro.rs index 4170f907b0ae..7a8faa62742a 100644 --- a/tests/used_underscore_binding_macro.rs +++ b/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 {