adding missing doc comments

This commit is contained in:
llogiq 2015-12-14 22:16:56 +01:00
parent 827082ac41
commit c645a9febe
9 changed files with 93 additions and 0 deletions

View file

@ -11,6 +11,13 @@ use rustc_front::intravisit::{Visitor, walk_expr};
use utils::{in_macro, LimitStack};
/// **What it does:** It `Warn`s on methods with high cyclomatic complexity
///
/// **Why is this bad?** Methods of high cyclomatic complexity tend to be badly readable. Also LLVM will usually optimize small methods better.
///
/// **Known problems:** Sometimes it's hard to find a way to reduce the complexity
///
/// **Example:** No. You'll see it when you get the warning.
declare_lint! { pub CYCLOMATIC_COMPLEXITY, Warn,
"finds functions that should be split up into multiple functions" }

View file

@ -19,6 +19,13 @@ declare_lint!(pub NEEDLESS_LIFETIMES, Warn,
"using explicit lifetimes for references in function arguments when elision rules \
would allow omitting them");
/// **What it does:** This lint checks for lifetimes in generics that are never used anywhere else. It is `Warn` by default.
///
/// **Why is this bad?** The additional lifetimes make the code look more complicated, while there is nothing out of the ordinary going on. Removing them leads to more readable code.
///
/// **Known problems:** None
///
/// **Example:** `fn unused_lifetime<'a>(x: u8) { .. }`
declare_lint!(pub UNUSED_LIFETIMES, Warn,
"unused lifetimes in function definitions");

View file

@ -114,6 +114,13 @@ declare_lint!{ pub EXPLICIT_COUNTER_LOOP, Warn,
/// **Example:** `loop {}`
declare_lint!{ pub EMPTY_LOOP, Warn, "empty `loop {}` detected" }
/// **What it does:** This lint checks for `while let` expressions on iterators. It is `Warn` by default.
///
/// **Why is this bad?** Readability. A simple `for` loop is shorter and conveys the intent better.
///
/// **Known problems:** None
///
/// **Example:** `while let Some(val) = iter() { .. }`
declare_lint!{ pub WHILE_LET_ON_ITERATOR, Warn, "using a while-let loop instead of a for loop on an iterator" }
#[derive(Copy, Clone)]

View file

@ -24,6 +24,7 @@ pub struct MethodsPass;
/// **Example:** `x.unwrap()`
declare_lint!(pub OPTION_UNWRAP_USED, Allow,
"using `Option.unwrap()`, which should at least get a better message using `expect()`");
/// **What it does:** This lint checks for `.unwrap()` calls on `Result`s. It is `Allow` by default.
///
/// **Why is this bad?** `result.unwrap()` will let the thread panic on `Err` values. Normally, you want to implement more sophisticated error handling, and propagate errors upwards with `try!`.
@ -35,6 +36,7 @@ declare_lint!(pub OPTION_UNWRAP_USED, Allow,
/// **Example:** `x.unwrap()`
declare_lint!(pub RESULT_UNWRAP_USED, Allow,
"using `Result.unwrap()`, which might be better handled");
/// **What it does:** This lint checks for `.to_string()` method calls on values of type `&str`. It is `Warn` by default.
///
/// **Why is this bad?** This uses the whole formatting machinery just to clone a string. Using `.to_owned()` is lighter on resources. You can also consider using a [`Cow<'a, str>`](http://doc.rust-lang.org/std/borrow/enum.Cow.html) instead in some cases.
@ -44,6 +46,7 @@ declare_lint!(pub RESULT_UNWRAP_USED, Allow,
/// **Example:** `s.to_string()` where `s: &str`
declare_lint!(pub STR_TO_STRING, Warn,
"using `to_string()` on a str, which should be `to_owned()`");
/// **What it does:** This lint checks for `.to_string()` method calls on values of type `String`. It is `Warn` by default.
///
/// **Why is this bad?** As our string is already owned, this whole operation is basically a no-op, but still creates a clone of the string (which, if really wanted, should be done with `.clone()`).
@ -53,6 +56,7 @@ declare_lint!(pub STR_TO_STRING, Warn,
/// **Example:** `s.to_string()` where `s: String`
declare_lint!(pub STRING_TO_STRING, Warn,
"calling `String.to_string()` which is a no-op");
/// **What it does:** This lint checks for methods that should live in a trait implementation of a `std` trait (see [llogiq's blog post](http://llogiq.github.io/2015/07/30/traits.html) for further information) instead of an inherent implementation. It is `Warn` by default.
///
/// **Why is this bad?** Implementing the traits improve ergonomics for users of the code, often with very little cost. Also people seeing a `mul(..)` method may expect `*` to work equally, so you should have good reason to disappoint them.
@ -68,6 +72,7 @@ declare_lint!(pub STRING_TO_STRING, Warn,
/// ```
declare_lint!(pub SHOULD_IMPLEMENT_TRAIT, Warn,
"defining a method that should be implementing a std trait");
/// **What it does:** This lint checks for methods with certain name prefixes and `Warn`s (by default) if the prefix doesn't match how self is taken. The actual rules are:
///
/// |Prefix |`self` taken |
@ -92,6 +97,7 @@ declare_lint!(pub SHOULD_IMPLEMENT_TRAIT, Warn,
declare_lint!(pub WRONG_SELF_CONVENTION, Warn,
"defining a method named with an established prefix (like \"into_\") that takes \
`self` with the wrong convention");
/// **What it does:** This is the same as [`wrong_self_convention`](#wrong_self_convention), but for public items. This lint is `Allow` by default.
///
/// **Why is this bad?** See [`wrong_self_convention`](#wrong_self_convention).
@ -107,12 +113,36 @@ declare_lint!(pub WRONG_SELF_CONVENTION, Warn,
declare_lint!(pub WRONG_PUB_SELF_CONVENTION, Allow,
"defining a public method named with an established prefix (like \"into_\") that takes \
`self` with the wrong convention");
/// **What it does:** This lint `Warn`s on using `ok().expect(..)`.
///
/// **Why is this bad?** Because you usually call `expect()` on the `Result` directly to get a good error message.
///
/// **Known problems:** None.
///
/// **Example:** `x.ok().expect("why did I do this again?")`
declare_lint!(pub OK_EXPECT, Warn,
"using `ok().expect()`, which gives worse error messages than \
calling `expect` directly on the Result");
/// **What it does:** This lint `Warn`s on `_.map(_).unwrap_or(_)`.
///
/// **Why is this bad?** Readability, this can be written more concisely as `_.map_or(_, _)`.
///
/// **Known problems:** None.
///
/// **Example:** `x.map(|a| a + 1).unwrap_or(0)`
declare_lint!(pub OPTION_MAP_UNWRAP_OR, Warn,
"using `Option.map(f).unwrap_or(a)`, which is more succinctly expressed as \
`map_or(a, f)`)");
/// **What it does:** This lint `Warn`s on `_.map(_).unwrap_or_else(_)`.
///
/// **Why is this bad?** Readability, this can be written more concisely as `_.map_or_else(_, _)`.
///
/// **Known problems:** None.
///
/// **Example:** `x.map(|a| a + 1).unwrap_or_else(some_function)`
declare_lint!(pub OPTION_MAP_UNWRAP_OR_ELSE, Warn,
"using `Option.map(f).unwrap_or_else(g)`, which is more succinctly expressed as \
`map_or_else(g, f)`)");

View file

@ -6,6 +6,13 @@ use syntax::ast::*;
use utils::span_lint;
/// **What it does:** This lint `Warn`s on struct field patterns bound to wildcards.
///
/// **Why is this bad?** Using `..` instead is shorter and leaves the focus on the fields that are actually bound.
///
/// **Known problems:** None.
///
/// **Example:** `let { a: _, b: ref b, c: _ } = ..`
declare_lint!(pub UNNEEDED_FIELD_PATTERN, Warn,
"Struct fields are bound to a wildcard instead of using `..`");

View file

@ -8,6 +8,13 @@ use rustc_front::hir::*;
use utils::span_lint;
use utils;
/// **What it does:** This lint `Warn`s on use of the `as_slice(..)` function, which is unstable.
///
/// **Why is this bad?** Using this function doesn't make your code better, but it will preclude it from building with stable Rust.
///
/// **Known problems:** None.
///
/// **Example:** `x.as_slice(..)`
declare_lint! {
pub UNSTABLE_AS_SLICE,
Warn,
@ -15,6 +22,13 @@ declare_lint! {
see https://github.com/rust-lang/rust/issues/27729"
}
/// **What it does:** This lint `Warn`s on use of the `as_mut_slice(..)` function, which is unstable.
///
/// **Why is this bad?** Using this function doesn't make your code better, but it will preclude it from building with stable Rust.
///
/// **Known problems:** None.
///
/// **Example:** `x.as_mut_slice(..)`
declare_lint! {
pub UNSTABLE_AS_MUT_SLICE,
Warn,

View file

@ -4,6 +4,13 @@ use rustc_front::hir::{Expr, ExprStruct};
use utils::span_lint;
/// **What it does:** This lint `Warn`s on needlessly including a base struct on update when all fields are changed anyway.
///
/// **Why is this bad?** This will cost resources (because the base has to be somewhere), and make the code less readable.
///
/// **Known problems:** None.
///
/// **Example:** `Point { x: 1, y: 0, ..zero_point }``
declare_lint! {
pub NEEDLESS_UPDATE,
Warn,

View file

@ -6,6 +6,13 @@ use rustc_front::hir::{Stmt, StmtSemi};
use utils::in_macro;
use utils::span_lint;
/// **What it does:** This lint `Warn`s on statements which have no effect.
///
/// **Why is this bad?** Similar to dead code, these statements are actually executed. However, as they have no effect, all they do is make the code less readable.
///
/// **Known problems:** None.
///
/// **Example:** `0;`
declare_lint! {
pub NO_EFFECT,
Warn,

View file

@ -4,6 +4,13 @@ use rustc_front::hir::{Expr, ExprAssign, ExprField, ExprStruct, ExprTup, ExprTup
use utils::is_adjusted;
use utils::span_lint;
/// **What it does:** This lint `Warn`s on creating a struct or tuple just to assign a value in it.
///
/// **Why is this bad?** Readability. If the struct is only created to be updated, why not write the struct you want in the first place?
///
/// **Known problems:** None.
///
/// **Example:** `(0, 0).0 = 1`
declare_lint! {
pub TEMPORARY_ASSIGNMENT,
Warn,