nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-12-01 19:23:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

For restriction lints, replace “Why is this bad?” with “Why restrict this?”

Browse Source 
The `restriction` group contains many lints which are not about
necessarily “bad” things, but style choices — perhaps even style choices
which contradict conventional Rust style — or are otherwise very
situational. This results in silly wording like “Why is this bad?
It isn't, but ...”, which I’ve seen confuse a newcomer at least once.

To improve this situation, this commit replaces the “Why is this bad?”
section heading with “Why restrict this?”, for most, but not all,
restriction lints. I left alone the ones whose placement in the
restriction group is more incidental.

In order to make this make sense, I had to remove the “It isn't, but”
texts from the contents of the sections. Sometimes further changes
were needed, or there were obvious fixes to make, and I went ahead
and made those changes without attempting to split them into another
commit, even though many of them are not strictly necessary for the
“Why restrict this?” project.
This commit is contained in:
Kevin Reid 2024-05-22 22:21:01 -07:00
parent 76856ffb57
commit 0f5338cd90
76 changed files with 306 additions and 245 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
book/src/development/adding_lints.md
View File

@ -587,6 +587,11 @@ declare_clippy_lint! {
}
```
If the lint is in the `restriction` group because it lints things that are not
necessarily “bad” but are more of a style choice, then replace the
“Why is this bad?” section heading with “Why restrict this?”, to avoid writing
“Why is this bad? It isn't, but ...”.
Once your lint is merged, this documentation will show up in the [lint
list][lint_list].

7
clippy_dev/src/new_lint.rs
View File

@ -331,12 +331,17 @@ fn get_lint_file_contents(lint: &LintData<'_>, enable_msrv: bool) -> String {
}
fn get_lint_declaration(name_upper: &str, category: &str) -> String {
let justification_heading = if category == "restriction" {
"Why restrict this?"
} else {
"Why is this bad?"
};
formatdoc!(
r#"
declare_clippy_lint! {{
/// ### What it does
///
/// ### Why is this bad?
/// ### {justification_heading}
///
/// ### Example
/// ```no_run

2
clippy_lints/src/absolute_paths.rs
View File

@ -12,7 +12,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of items through absolute paths, like `std::env::current_dir`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Many codebases have their own style when it comes to importing, but one that is seldom used
/// is using absolute paths *everywhere*. This is generally considered unidiomatic, and you
/// should add a `use` statement.

7
clippy_lints/src/allow_attributes.rs
View File

@ -19,10 +19,11 @@ declare_clippy_lint! {
/// This lint only warns outer attributes (`#[allow]`), as inner attributes
/// (`#![allow]`) are usually used to enable or disable lints on a global scale.
///
/// ### Why is this bad?
/// `#[expect]` attributes suppress the lint emission, but emit a warning, if
/// ### Why restrict this?
/// `#[allow]` attributes can linger after their reason for existence is gone.
/// `#[expect]` attributes suppress the lint emission, but emit a warning if
/// the expectation is unfulfilled. This can be useful to be notified when the
/// lint is no longer triggered.
/// lint is no longer triggered, which may indicate the attribute can be removed.
///
/// ### Example
/// ```rust,ignore

2
clippy_lints/src/as_conversions.rs
View File

@ -17,7 +17,7 @@ declare_clippy_lint! {
/// There is a good explanation the reason why this lint should work in this way and how it is useful
/// [in this issue](https://github.com/rust-lang/rust-clippy/issues/5122).
///
/// ### Why is this bad?
/// ### Why restrict this?
/// `as` conversions will perform many kinds of
/// conversions, including silently lossy conversions and dangerous coercions.
/// There are cases when it makes sense to use `as`, so the lint is

10
clippy_lints/src/asm_syntax.rs
View File

@ -65,9 +65,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of Intel x86 assembly syntax.
///
/// ### Why is this bad?
/// The lint has been enabled to indicate a preference
/// for AT&T x86 assembly syntax.
/// ### Why restrict this?
/// To enforce consistent use of AT&T x86 assembly syntax.
///
/// ### Example
///
@ -114,9 +113,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of AT&T x86 assembly syntax.
///
/// ### Why is this bad?
/// The lint has been enabled to indicate a preference
/// for Intel x86 assembly syntax.
/// ### Why restrict this?
/// To enforce consistent use of Intel x86 assembly syntax.
///
/// ### Example
///

20
clippy_lints/src/assertions_on_result_states.rs
View File

@ -16,23 +16,33 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `assert!(r.is_ok())` or `assert!(r.is_err())` calls.
///
/// ### Why is this bad?
/// An assertion failure cannot output an useful message of the error.
/// ### Why restrict this?
/// This form of assertion does not show any of the information present in the `Result`
/// other than which variant it isn’t.
///
/// ### Known problems
/// The suggested replacement decreases the readability of code and log output.
///
/// ### Example
/// ```rust,ignore
/// ```rust,no_run
/// # let r = Ok::<_, ()>(());
/// assert!(r.is_ok());
/// # let r = Err::<_, ()>(());
/// # let r = Err::<(), _>(());
/// assert!(r.is_err());
/// ```
///
/// Use instead:
///
/// ```rust,no_run
/// # let r = Ok::<_, ()>(());
/// r.unwrap();
/// # let r = Err::<(), _>(());
/// r.unwrap_err();
/// ```
#[clippy::version = "1.64.0"]
pub ASSERTIONS_ON_RESULT_STATES,
restriction,
"`assert!(r.is_ok())`/`assert!(r.is_err())` gives worse error message than directly calling `r.unwrap()`/`r.unwrap_err()`"
"`assert!(r.is_ok())` or `assert!(r.is_err())` gives worse panic messages than directly calling `r.unwrap()` or `r.unwrap_err()`"
}
declare_lint_pass!(AssertionsOnResultStates => [ASSERTIONS_ON_RESULT_STATES]);

6
clippy_lints/src/attrs/mod.rs
View File

@ -309,9 +309,9 @@ declare_clippy_lint! {
///
/// (This requires the `lint_reasons` feature)
///
/// ### Why is this bad?
/// Allowing a lint should always have a reason. This reason should be documented to
/// ensure that others understand the reasoning
/// ### Why restrict this?
/// Justifying each `allow` helps readers understand the reasoning,
/// and may allow removing `allow` attributes if their purpose is obsolete.
///
/// ### Example
/// ```no_run

6
clippy_lints/src/casts/mod.rs
View File

@ -303,7 +303,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for casts of a function pointer to any integer type.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Casting a function pointer to an integer can have surprising results and can occur
/// accidentally if parentheses are omitted from a function call. If you aren't doing anything
/// low-level with function pointers then you can opt-out of casting functions to integers in
@ -535,8 +535,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for the usage of `as _` conversion using inferred type.
///
/// ### Why is this bad?
/// The conversion might include lossy conversion and dangerous cast that might go
/// ### Why restrict this?
/// The conversion might include lossy conversion or a dangerous cast that might go
/// undetected due to the type being inferred.
///
/// The lint is allowed by default as using `_` is less wordy than always specifying the type.

6
clippy_lints/src/create_dir.rs
View File

@ -10,8 +10,10 @@ declare_clippy_lint! {
/// ### What it does
/// Checks usage of `std::fs::create_dir` and suggest using `std::fs::create_dir_all` instead.
///
/// ### Why is this bad?
/// Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`.
/// ### Why restrict this?
/// Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`,
/// resulting in failure when more than one directory needs to be created or when the directory already exists.
/// Crates which never need to specifically create a single directory may wish to prevent this mistake.
///
/// ### Example
/// ```rust,ignore

2
clippy_lints/src/dbg_macro.rs
View File

@ -14,7 +14,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of the [`dbg!`](https://doc.rust-lang.org/std/macro.dbg.html) macro.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// The `dbg!` macro is intended as a debugging tool. It should not be present in released
/// software or committed to a version control system.
///

5
clippy_lints/src/default_numeric_fallback.rs
View File

@ -22,9 +22,8 @@ declare_clippy_lint! {
///
/// See [RFC0212](https://github.com/rust-lang/rfcs/blob/master/text/0212-restore-int-fallback.md) for more information about the fallback.
///
/// ### Why is this bad?
/// For those who are very careful about types, default numeric fallback
/// can be a pitfall that cause unexpected runtime behavior.
/// ### Why restrict this?
/// To ensure that every numeric type is chosen explicitly rather than implicitly.
///
/// ### Known problems
/// This lint can only be allowed at the function level or above.

2
clippy_lints/src/default_union_representation.rs
View File

@ -10,7 +10,7 @@ declare_clippy_lint! {
/// ### What it does
/// Displays a warning when a union is declared with the default representation (without a `#[repr(C)]` attribute).
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Unions in Rust have unspecified layout by default, despite many people thinking that they
/// lay out each field at the start of the union (like C does). That is, there are no guarantees
/// about the offset of the fields for unions with multiple non-ZST fields without an explicitly

4
clippy_lints/src/disallowed_script_idents.rs
View File

@ -20,11 +20,11 @@ declare_clippy_lint! {
/// [aliases]: http://www.unicode.org/reports/tr24/tr24-31.html#Script_Value_Aliases
/// [supported_scripts]: https://www.unicode.org/iso15924/iso15924-codes.html
///
/// ### Why is this bad?
/// ### Why restrict this?
/// It may be not desired to have many different scripts for
/// identifiers in the codebase.
///
/// Note that if you only want to allow plain English, you might want to use
/// Note that if you only want to allow typical English, you might want to use
/// built-in [`non_ascii_idents`] lint instead.
///
/// [`non_ascii_idents`]: https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#non-ascii-idents

2
clippy_lints/src/doc/mod.rs
View File

@ -261,7 +261,7 @@ declare_clippy_lint! {
/// Checks for the doc comments of publicly visible
/// safe functions and traits and warns if there is a `# Safety` section.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Safe functions and traits are safe to implement and therefore do not
/// need to describe safety preconditions that users are required to uphold.
///

7
clippy_lints/src/drop_forget_ref.rs
View File

@ -52,9 +52,10 @@ declare_clippy_lint! {
/// Checks for usage of `std::mem::forget(t)` where `t` is
/// `Drop` or has a field that implements `Drop`.
///
/// ### Why is this bad?
/// `std::mem::forget(t)` prevents `t` from running its
/// destructor, possibly causing leaks.
/// ### Why restrict this?
/// `std::mem::forget(t)` prevents `t` from running its destructor, possibly causing leaks.
/// It is not possible to detect all means of creating leaks, but it may be desirable to
/// prohibit the simple ones.
///
/// ### Example
/// ```no_run

2
clippy_lints/src/else_if_without_else.rs
View File

@ -11,7 +11,7 @@ declare_clippy_lint! {
/// Checks for usage of if expressions with an `else if` branch,
/// but without a final `else` branch.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Some coding guidelines require this (e.g., MISRA-C:2004 Rule 14.10).
///
/// ### Example

2
clippy_lints/src/empty_drop.rs
View File

@ -9,7 +9,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for empty `Drop` implementations.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Empty `Drop` implementations have no effect when dropping an instance of the type. They are
/// most likely useless. However, an empty `Drop` implementation prevents a type from being
/// destructured, which might be the intention behind adding the implementation as a marker.

24
clippy_lints/src/empty_with_brackets.rs
View File

@ -11,16 +11,23 @@ declare_clippy_lint! {
/// ### What it does
/// Finds structs without fields (a so-called "empty struct") that are declared with brackets.
///
/// ### Why is this bad?
/// Empty brackets after a struct declaration can be omitted.
/// ### Why restrict this?
/// Empty brackets after a struct declaration can be omitted,
/// and it may be desirable to do so consistently for style.
///
/// However, removing the brackets also introduces a public constant named after the struct,
/// so this is not just a syntactic simplification but an an API change, and adding them back
/// is a *breaking* API change.
///
/// ### Example
/// ```no_run
/// struct Cookie {}
/// struct Biscuit();
/// ```
/// Use instead:
/// ```no_run
/// struct Cookie;
/// struct Biscuit;
/// ```
#[clippy::version = "1.62.0"]
pub EMPTY_STRUCTS_WITH_BRACKETS,
@ -32,14 +39,20 @@ declare_clippy_lint! {
/// ### What it does
/// Finds enum variants without fields that are declared with empty brackets.
///
/// ### Why is this bad?
/// Empty brackets while defining enum variants are redundant and can be omitted.
/// ### Why restrict this?
/// Empty brackets after a enum variant declaration are redundant and can be omitted,
/// and it may be desirable to do so consistently for style.
///
/// However, removing the brackets also introduces a public constant named after the variant,
/// so this is not just a syntactic simplification but an an API change, and adding them back
/// is a *breaking* API change.
///
/// ### Example
/// ```no_run
/// enum MyEnum {
/// HasData(u8),
/// HasNoData(), // redundant parentheses
/// HasNoData(), // redundant parentheses
/// NoneHereEither {}, // redundant braces
/// }
/// ```
///
@ -48,6 +61,7 @@ declare_clippy_lint! {
/// enum MyEnum {
/// HasData(u8),
/// HasNoData,
/// NoneHereEither,
/// }
/// ```
#[clippy::version = "1.77.0"]

15
clippy_lints/src/endian_bytes.rs
View File

@ -13,8 +13,9 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for the usage of the `to_ne_bytes` method and/or the function `from_ne_bytes`.
///
/// ### Why is this bad?
/// It's not, but some may prefer to specify the target endianness explicitly.
/// ### Why restrict this?
/// To ensure use of explicitly chosen endianness rather than the target’s endianness,
/// such as when implementing network protocols or file formats rather than FFI.
///
/// ### Example
/// ```rust,ignore
@ -31,9 +32,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for the usage of the `to_le_bytes` method and/or the function `from_le_bytes`.
///
/// ### Why is this bad?
/// It's not, but some may wish to lint usage of this method, either to suggest using the host
/// endianness or big endian.
/// ### Why restrict this?
/// To ensure use of big endian or the target’s endianness rather than little endian.
///
/// ### Example
/// ```rust,ignore
@ -50,9 +50,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for the usage of the `to_be_bytes` method and/or the function `from_be_bytes`.
///
/// ### Why is this bad?
/// It's not, but some may wish to lint usage of this method, either to suggest using the host
/// endianness or little endian.
/// ### Why restrict this?
/// To ensure use of little endian or the target’s endianness rather than big endian.
///
/// ### Example
/// ```rust,ignore

2
clippy_lints/src/error_impl_error.rs
View File

@ -12,7 +12,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for types named `Error` that implement `Error`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// It can become confusing when a codebase has 20 types all named `Error`, requiring either
/// aliasing them in the `use` statement or qualifying them like `my_module::Error`. This
/// hinders comprehension, as it requires you to memorize every variation of importing `Error`

16
clippy_lints/src/exhaustive_items.rs
View File

@ -10,10 +10,10 @@ declare_clippy_lint! {
/// ### What it does
/// Warns on any exported `enum`s that are not tagged `#[non_exhaustive]`
///
/// ### Why is this bad?
/// Exhaustive enums are typically fine, but a project which does
/// not wish to make a stability commitment around exported enums may wish to
/// disable them by default.
/// ### Why restrict this?
/// Making an `enum` exhaustive is a stability commitment: adding a variant is a breaking change.
/// A project may wish to ensure that there are no exhaustive enums or that every exhaustive
/// `enum` is explicitly `#[allow]`ed.
///
/// ### Example
/// ```no_run
@ -40,10 +40,10 @@ declare_clippy_lint! {
/// ### What it does
/// Warns on any exported `struct`s that are not tagged `#[non_exhaustive]`
///
/// ### Why is this bad?
/// Exhaustive structs are typically fine, but a project which does
/// not wish to make a stability commitment around exported structs may wish to
/// disable them by default.
/// ### Why restrict this?
/// Making a `struct` exhaustive is a stability commitment: adding a field is a breaking change.
/// A project may wish to ensure that there are no exhaustive structs or that every exhaustive
/// `struct` is explicitly `#[allow]`ed.
///
/// ### Example
/// ```no_run

12
clippy_lints/src/exit.rs
View File

@ -9,11 +9,13 @@ declare_clippy_lint! {
/// ### What it does
/// Detects calls to the `exit()` function which terminates the program.
///
/// ### Why is this bad?
/// Exit terminates the program at the location it is called. For unrecoverable
/// errors `panics` should be used to provide a stacktrace and potentially other
/// information. A normal termination or one with an error code should happen in
/// the main function.
/// ### Why restrict this?
/// `exit()` immediately terminates the program with no information other than an exit code.
/// This provides no means to troubleshoot a problem, and may be an unexpected side effect.
///
/// Codebases may use this lint to require that all exits are performed either by panicking
/// (which produces a message, a code location, and optionally a backtrace)
/// or by returning from `main()` (which is a single place to look).
///
/// ### Example
/// ```no_run

6
clippy_lints/src/float_literal.rs
View File

@ -38,9 +38,9 @@ declare_clippy_lint! {
/// Checks for whole number float literals that
/// cannot be represented as the underlying type without loss.
///
/// ### Why is this bad?
/// Rust will silently lose precision during
/// conversion to a float.
/// ### Why restrict this?
/// If the value was intended to be exact, it will not be.
/// This may be especially surprising when the lost precision is to the left of the decimal point.
///
/// ### Example
/// ```no_run

2
clippy_lints/src/format_push_string.rs
View File

@ -11,7 +11,7 @@ declare_clippy_lint! {
/// Detects cases where the result of a `format!` call is
/// appended to an existing `String`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Introduces an extra, avoidable heap allocation.
///
/// ### Known problems

11
clippy_lints/src/functions/mod.rs
View File

@ -338,8 +338,10 @@ declare_clippy_lint! {
declare_clippy_lint! {
/// ### What it does
/// Lints when `impl Trait` is being used in a function's parameters.
/// ### Why is this bad?
/// Turbofish syntax (`::<>`) cannot be used when `impl Trait` is being used, making `impl Trait` less powerful. Readability may also be a factor.
///
/// ### Why restrict this?
/// Turbofish syntax (`::<>`) cannot be used to specify the type of an `impl Trait` parameter,
/// making `impl Trait` less powerful. Readability may also be a factor.
///
/// ### Example
/// ```no_run
@ -366,9 +368,8 @@ declare_clippy_lint! {
/// Lints when the name of function parameters from trait impl is
/// different than its default implementation.
///
/// ### Why is this bad?
/// Using the default name for parameters of a trait method is often
/// more desirable for consistency's sake.
/// ### Why restrict this?
/// Using the default name for parameters of a trait method is more consistent.
///
/// ### Example
/// ```rust

2
clippy_lints/src/if_then_some_else_none.rs
View File

@ -15,7 +15,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for if-else that could be written using either `bool::then` or `bool::then_some`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Looks a little redundant. Using `bool::then` is more concise and incurs no loss of clarity.
/// For simple calculations and known values, use `bool::then_some`, which is eagerly evaluated
/// in comparison to `bool::then`.

13
clippy_lints/src/implicit_return.rs
View File

@ -16,12 +16,13 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for missing return statements at the end of a block.
///
/// ### Why is this bad?
/// Actually omitting the return keyword is idiomatic Rust code. Programmers
/// coming from other languages might prefer the expressiveness of `return`. It's possible to miss
/// the last returning statement because the only difference is a missing `;`. Especially in bigger
/// code with multiple return paths having a `return` keyword makes it easier to find the
/// corresponding statements.
/// ### Why restrict this?
/// Omitting the return keyword whenever possible is idiomatic Rust code, but:
///
/// * Programmers coming from other languages might prefer the expressiveness of `return`.
/// * It's possible to miss the last returning statement because the only difference is a missing `;`.
/// * Especially in bigger code with multiple return paths, having a `return` keyword makes it easier to find the
/// corresponding statements.
///
/// ### Example
/// ```no_run

7
clippy_lints/src/indexing_slicing.rs
View File

@ -45,9 +45,10 @@ declare_clippy_lint! {
/// does report on arrays if we can tell that slicing operations are in bounds and does not
/// lint on constant `usize` indexing on arrays because that is handled by rustc's `const_err` lint.
///
/// ### Why is this bad?
/// Indexing and slicing can panic at runtime and there are
/// safe alternatives.
/// ### Why restrict this?
/// To avoid implicit panics from indexing and slicing.
/// There are “checked” alternatives which do not panic, and can be used with `unwrap()` to make
/// an explicit panic when it is desired.
///
/// ### Example
/// ```rust,no_run

2
clippy_lints/src/inherent_impl.rs
View File

@ -14,7 +14,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for multiple inherent implementations of a struct
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Splitting the implementation of a type makes the code harder to navigate.
///
/// ### Example

6
clippy_lints/src/integer_division_remainder_used.rs
View File

@ -7,10 +7,10 @@ use rustc_session::declare_lint_pass;
declare_clippy_lint! {
/// ### What it does
/// Checks for the usage of division (/) and remainder (%) operations
/// when performed on any integer types using the default Div and Rem trait implementations.
/// Checks for the usage of division (`/`) and remainder (`%`) operations
/// when performed on any integer types using the default `Div` and `Rem` trait implementations.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// In cryptographic contexts, division can result in timing sidechannel vulnerabilities,
/// and needs to be replaced with constant-time code instead (e.g. Barrett reduction).
///

4
clippy_lints/src/iter_over_hash_type.rs
View File

@ -14,8 +14,8 @@ declare_clippy_lint! {
/// ### What it does
/// This is a restriction lint which prevents the use of hash types (i.e., `HashSet` and `HashMap`) in for loops.
///
/// ### Why is this bad?
/// Because hash types are unordered, when iterated through such as in a for loop, the values are returned in
/// ### Why restrict this?
/// Because hash types are unordered, when iterated through such as in a `for` loop, the values are returned in
/// an undefined order. As a result, on redundant systems this may cause inconsistencies and anomalies.
/// In addition, the unknown order of the elements may reduce readability or introduce other undesired
/// side effects.

8
clippy_lints/src/large_include_file.rs
View File

@ -10,10 +10,12 @@ use rustc_span::sym;
declare_clippy_lint! {
/// ### What it does
/// Checks for the inclusion of large files via `include_bytes!()`
/// and `include_str!()`
/// or `include_str!()`.
///
/// ### Why is this bad?
/// Including large files can increase the size of the binary
/// ### Why restrict this?
/// Including large files can undesirably increase the size of the binary produced by the compiler.
/// This lint may be used to catch mistakes where an unexpectedly large file is included, or
/// temporarily to obtain a list of all large files.
///
/// ### Example
/// ```rust,ignore

9
clippy_lints/src/let_underscore.rs
View File

@ -12,9 +12,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `let _ = <expr>` where expr is `#[must_use]`
///
/// ### Why is this bad?
/// It's better to explicitly handle the value of a `#[must_use]`
/// expr
/// ### Why restrict this?
/// To ensure that all `#[must_use]` types are used rather than ignored.
///
/// ### Example
/// ```no_run
@ -96,8 +95,8 @@ declare_clippy_lint! {
/// Checks for `let _ = <expr>` without a type annotation, and suggests to either provide one,
/// or remove the `let` keyword altogether.
///
/// ### Why is this bad?
/// The `let _ = <expr>` expression ignores the value of `<expr>` but will remain doing so even
/// ### Why restrict this?
/// The `let _ = <expr>` expression ignores the value of `<expr>`, but will continue to do so even
/// if the type were to change, thus potentially introducing subtle bugs. By supplying a type
/// annotation, one will be forced to re-visit the decision to ignore the value in such cases.
///

4
clippy_lints/src/literal_representation.rs
View File

@ -132,8 +132,8 @@ declare_clippy_lint! {
/// ### What it does
/// Warns if there is a better representation for a numeric literal.
///
/// ### Why is this bad?
/// Especially for big powers of 2 a hexadecimal representation is more
/// ### Why restrict this?
/// Especially for big powers of 2, a hexadecimal representation is usually more
/// readable than a decimal representation.
///
/// ### Example

6
clippy_lints/src/loops/mod.rs
View File

@ -675,9 +675,9 @@ declare_clippy_lint! {
/// Checks for infinite loops in a function where the return type is not `!`
/// and lint accordingly.
///
/// ### Why is this bad?
/// A loop should be gently exited somewhere, or at least mark its parent function as
/// never return (`!`).
/// ### Why restrict this?
/// Making the return type `!` serves as documentation that the function does not return.
/// If the function is not intended to loop infinitely, then this lint may detect a bug.
///
/// ### Example
/// ```no_run,ignore

6
clippy_lints/src/matches/mod.rs
View File

@ -260,7 +260,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for wildcard enum matches using `_`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// New enum variants added by library updates can be missed.
///
/// ### Known problems
@ -435,7 +435,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for unnecessary '..' pattern binding on struct when all fields are explicitly matched.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Correctness and readability. It's like having a wildcard pattern after
/// matching all enum variants explicitly.
///
@ -861,7 +861,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of `Err(x)?`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// The `?` operator is designed to allow calls that
/// can fail to be easily chained. For example, `foo()?.bar()` or
/// `foo(bar()?)`. Because `Err(x)?` can't be used that way (it will

21
clippy_lints/src/methods/mod.rs
View File

@ -257,7 +257,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `.unwrap()` or `.unwrap_err()` calls on `Result`s and `.unwrap()` call on `Option`s.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// It is better to handle the `None` or `Err` case,
/// or at least call `.expect(_)` with a more helpful message. Still, for a lot of
/// quick-and-dirty code, `unwrap` is a good choice, which is why this lint is
@ -333,7 +333,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `.expect()` or `.expect_err()` calls on `Result`s and `.expect()` call on `Option`s.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Usually it is better to handle the `None` or `Err` case.
/// Still, for a lot of quick-and-dirty code, `expect` is a good choice, which is why
/// this lint is `Allow` by default.
@ -1029,8 +1029,8 @@ declare_clippy_lint! {
/// (`Rc`, `Arc`, `rc::Weak`, or `sync::Weak`), and suggests calling Clone via unified
/// function syntax instead (e.g., `Rc::clone(foo)`).
///
/// ### Why is this bad?
/// Calling '.clone()' on an Rc, Arc, or Weak
/// ### Why restrict this?
/// Calling `.clone()` on an `Rc`, `Arc`, or `Weak`
/// can obscure the fact that only the pointer is being cloned, not the underlying
/// data.
///
@ -1051,7 +1051,7 @@ declare_clippy_lint! {
#[clippy::version = "pre 1.29.0"]
pub CLONE_ON_REF_PTR,
restriction,
"using 'clone' on a ref-counted pointer"
"using `clone` on a ref-counted pointer"
}
declare_clippy_lint! {
@ -1359,7 +1359,7 @@ declare_clippy_lint! {
/// Checks for usage of `.get().unwrap()` (or
/// `.get_mut().unwrap`) on a standard library type which implements `Index`
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Using the Index trait (`[]`) is more clear and more
/// concise.
///
@ -1743,7 +1743,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `FileType::is_file()`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// When people testing a file type with `FileType::is_file`
/// they are testing whether a path is something they can get bytes from. But
/// `is_file` doesn't cover special file types in unix-like systems, and doesn't cover
@ -2688,8 +2688,9 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for instances of `map_err(|_| Some::Enum)`
///
/// ### Why is this bad?
/// This `map_err` throws away the original error rather than allowing the enum to contain and report the cause of the error
/// ### Why restrict this?
/// This `map_err` throws away the original error rather than allowing the enum to
/// contain and report the cause of the error.
///
/// ### Example
/// Before:
@ -3145,7 +3146,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of File::read_to_end and File::read_to_string.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// `fs::{read, read_to_string}` provide the same functionality when `buf` is empty with fewer imports and no intermediate values.
/// See also: [fs::read docs](https://doc.rust-lang.org/std/fs/fn.read.html), [fs::read_to_string docs](https://doc.rust-lang.org/std/fs/fn.read_to_string.html)
///

7
clippy_lints/src/min_ident_chars.rs
View File

@ -12,14 +12,13 @@ use std::borrow::Cow;
declare_clippy_lint! {
/// ### What it does
/// Checks for idents which comprise of a single letter.
/// Checks for identifiers which consist of a single character (or fewer than the configured threshold).
///
/// Note: This lint can be very noisy when enabled; it may be desirable to only enable it
/// temporarily.
///
/// ### Why is this bad?
/// In many cases it's not, but at times it can severely hinder readability. Some codebases may
/// wish to disallow this to improve readability.
/// ### Why restrict this?
/// To improve readability by requiring that every variable has a name more specific than a single letter can be.
///
/// ### Example
/// ```rust,ignore

6
clippy_lints/src/misc_early/mod.rs
View File

@ -23,7 +23,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for structure field patterns bound to wildcards.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Using `..` instead is shorter and leaves the focus on
/// the fields that are actually bound.
///
@ -138,7 +138,7 @@ declare_clippy_lint! {
/// To enforce unseparated literal suffix style,
/// see the `separated_literal_suffix` lint.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Suffix style should be consistent.
///
/// ### Example
@ -166,7 +166,7 @@ declare_clippy_lint! {
/// To enforce separated literal suffix style,
/// see the `unseparated_literal_suffix` lint.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Suffix style should be consistent.
///
/// ### Example

2
clippy_lints/src/missing_assert_message.rs
View File

@ -10,7 +10,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks assertions without a custom panic message.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Without a good custom message, it'd be hard to understand what went wrong when the assertion fails.
/// A good custom message should be more about why the failure of the assertion is problematic
/// and not what is failed because the assertion already conveys that.

2
clippy_lints/src/missing_asserts_for_indexing.rs
View File

@ -21,7 +21,7 @@ declare_clippy_lint! {
/// Checks for repeated slice indexing without asserting beforehand that the length
/// is greater than the largest index used to index into the slice.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// In the general case where the compiler does not have a lot of information
/// about the length of a slice, indexing it repeatedly will generate a bounds check
/// for every single index.

4
clippy_lints/src/missing_doc.rs
View File

@ -20,9 +20,9 @@ use rustc_span::{sym, Span};
declare_clippy_lint! {
/// ### What it does
/// Warns if there is missing doc for any private documentable item
/// Warns if there is missing documentation for any private documentable item.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Doc is good. *rustc* has a `MISSING_DOCS`
/// allowed-by-default lint for
/// public members, but has no way to enforce documentation of private items.

19
clippy_lints/src/missing_inline.rs
View File

@ -10,13 +10,16 @@ declare_clippy_lint! {
/// It lints if an exported function, method, trait method with default impl,
/// or trait method impl is not `#[inline]`.
///
/// ### Why is this bad?
/// In general, it is not. Functions can be inlined across
/// crates when that's profitable as long as any form of LTO is used. When LTO is disabled,
/// functions that are not `#[inline]` cannot be inlined across crates. Certain types of crates
/// might intend for most of the methods in their public API to be able to be inlined across
/// crates even when LTO is disabled. For these types of crates, enabling this lint might make
/// sense. It allows the crate to require all exported methods to be `#[inline]` by default, and
/// ### Why restrict this?
/// When a function is not marked `#[inline]`, it is not
/// [a “small” candidate for automatic inlining][small], and LTO is not in use, then it is not
/// possible for the function to be inlined into the code of any crate other than the one in
/// which it is defined. Depending on the role of the function and the relationship of the crates,
/// this could significantly reduce performance.
///
/// Certain types of crates might intend for most of the methods in their public API to be able
/// to be inlined across crates even when LTO is disabled.
/// This lint allows those crates to require all exported methods to be `#[inline]` by default, and
/// then opt out for specific methods where this might not make sense.
///
/// ### Example
@ -51,6 +54,8 @@ declare_clippy_lint! {
/// fn def_bar() {} // missing #[inline]
/// }
/// ```
///
/// [small]: https://github.com/rust-lang/rust/pull/116505
#[clippy::version = "pre 1.29.0"]
pub MISSING_INLINE_IN_PUBLIC_ITEMS,
restriction,

10
clippy_lints/src/missing_trait_methods.rs
View File

@ -10,16 +10,16 @@ use rustc_session::declare_lint_pass;
declare_clippy_lint! {
/// ### What it does
/// Checks if a provided method is used implicitly by a trait
/// implementation. A usage example would be a wrapper where every method
/// should perform some operation before delegating to the inner type's
/// implementation.
///
/// ### Why restrict this?
/// To ensure that a certain implementation implements every method; for example,
/// a wrapper type where every method should delegate to the corresponding method of
/// the inner type's implementation.
///
/// This lint should typically be enabled on a specific trait `impl` item
/// rather than globally.
///
/// ### Why is this bad?
/// Indicates that a method is missing.
///
/// ### Example
/// ```no_run
/// trait Trait {

9
clippy_lints/src/mixed_read_write_in_expression.rs
View File

@ -12,9 +12,10 @@ declare_clippy_lint! {
/// whether the read occurs before or after the write depends on the evaluation
/// order of sub-expressions.
///
/// ### Why is this bad?
/// It is often confusing to read. As described [here](https://doc.rust-lang.org/reference/expressions.html?highlight=subexpression#evaluation-order-of-operands),
/// the operands of these expressions are evaluated before applying the effects of the expression.
/// ### Why restrict this?
/// While [the evaluation order of sub-expressions] is fully specified in Rust,
/// it still may be confusing to read an expression where the evaluation order
/// affects its behavior.
///
/// ### Known problems
/// Code which intentionally depends on the evaluation
@ -40,6 +41,8 @@ declare_clippy_lint! {
/// };
/// let a = tmp + x;
/// ```
///
/// [order]: (https://doc.rust-lang.org/reference/expressions.html?highlight=subexpression#evaluation-order-of-operands)
#[clippy::version = "pre 1.29.0"]
pub MIXED_READ_WRITE_IN_EXPRESSION,
restriction,

6
clippy_lints/src/module_style.rs
View File

@ -10,9 +10,9 @@ use std::path::{Component, Path};
declare_clippy_lint! {
/// ### What it does
/// Checks that module layout uses only self named module files, bans `mod.rs` files.
/// Checks that module layout uses only self named module files; bans `mod.rs` files.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Having multiple module layout styles in a project can be confusing.
///
/// ### Example
@ -41,7 +41,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks that module layout uses only `mod.rs` files.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Having multiple module layout styles in a project can be confusing.
///
/// ### Example

2
clippy_lints/src/multiple_unsafe_ops_per_block.rs
View File

@ -15,7 +15,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `unsafe` blocks that contain more than one unsafe operation.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Combined with `undocumented_unsafe_blocks`,
/// this lint ensures that each unsafe operation must be independently justified.
/// Combined with `unused_unsafe`, this lint also ensures

2
clippy_lints/src/mutex_atomic.rs
View File

@ -14,7 +14,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of `Mutex<X>` where an atomic will do.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Using a mutex just to make access to a plain bool or
/// reference sequential is shooting flies with cannons.
/// `std::sync::atomic::AtomicBool` and `std::sync::atomic::AtomicPtr` are leaner and

12
clippy_lints/src/operators/mod.rs
View File

@ -70,7 +70,7 @@ declare_clippy_lint! {
/// Known safe built-in types like `Wrapping` or `Saturating`, floats, operations in constant
/// environments, allowed types and non-constant operations that won't overflow are ignored.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// For integers, overflow will trigger a panic in debug builds or wrap the result in
/// release mode; division by zero will cause a panic in either mode. As a result, it is
/// desirable to explicitly call checked, wrapping or saturating arithmetic methods.
@ -100,7 +100,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for float arithmetic.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// For some embedded systems or kernel development, it
/// can be useful to rule out floating-point numbers.
///
@ -502,7 +502,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for division of integers
///
/// ### Why is this bad?
/// ### Why restrict this?
/// When outside of some very specific algorithms,
/// integer division is very often a mistake because it discards the
/// remainder.
@ -596,7 +596,7 @@ declare_clippy_lint! {
/// value and constant, except in functions called `*eq*` (which probably
/// implement equality for a type involving floats).
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Floating point calculations are usually imprecise, so
/// asking if two values are *exactly* equal is asking for trouble. For a good
/// guide on what to do, see [the floating point
@ -653,8 +653,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for modulo arithmetic.
///
/// ### Why is this bad?
/// The results of modulo (%) operation might differ
/// ### Why restrict this?
/// The results of modulo (`%`) operation might differ
/// depending on the language, when negative numbers are involved.
/// If you interop with different languages it might be beneficial
/// to double check all places that use modulo arithmetic.

4
clippy_lints/src/panic_in_result_fn.rs
View File

@ -13,9 +13,9 @@ use rustc_span::{sym, Span};
declare_clippy_lint! {
/// ### What it does
/// Checks for usage of `panic!` or assertions in a function of type result.
/// Checks for usage of `panic!` or assertions in a function whose return type is `Result`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// For some codebases, it is desirable for functions of type result to return an error instead of crashing. Hence panicking macros should be avoided.
///
/// ### Known problems

18
clippy_lints/src/panic_unimplemented.rs
View File

@ -14,8 +14,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of `panic!`.
///
/// ### Why is this bad?
/// `panic!` will stop the execution of the executable.
/// ### Why restrict this?
/// This macro, or panics in general, may be unwanted in production code.
///
/// ### Example
/// ```no_run
@ -31,8 +31,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of `unimplemented!`.
///
/// ### Why is this bad?
/// This macro should not be present in production code.
/// ### Why restrict this?
/// This macro, or panics in general, may be unwanted in production code.
///
/// ### Example
/// ```no_run
@ -48,9 +48,9 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of `todo!`.
///
/// ### Why is this bad?
/// The `todo!` macro is often used for unfinished code, and it causes
/// code to panic. It should not be present in production code.
/// ### Why restrict this?
/// The `todo!` macro indicates the presence of unfinished code,
/// so it should not be present in production code.
///
/// ### Example
/// ```no_run
@ -70,8 +70,8 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of `unreachable!`.
///
/// ### Why is this bad?
/// This macro can cause code to panic.
/// ### Why restrict this?
/// This macro, or panics in general, may be unwanted in production code.
///
/// ### Example
/// ```no_run

9
clippy_lints/src/partial_pub_fields.rs
View File

@ -5,15 +5,16 @@ use rustc_session::declare_lint_pass;
declare_clippy_lint! {
/// ### What it does
/// Checks whether partial fields of a struct are public.
/// Checks whether some but not all fields of a `struct` are public.
///
/// Either make all fields of a type public, or make none of them public
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Most types should either be:
/// * Abstract data types: complex objects with opaque implementation which guard
/// interior invariants and expose intentionally limited API to the outside world.
/// * Data: relatively simple objects which group a bunch of related attributes together.
/// interior invariants and expose intentionally limited API to the outside world.
/// * Data: relatively simple objects which group a bunch of related attributes together,
/// but have no invariants.
///
/// ### Example
/// ```no_run

5
clippy_lints/src/pattern_type_mismatch.rs
View File

@ -30,9 +30,8 @@ declare_clippy_lint! {
/// this lint can still be used to highlight areas of interest and ensure a good understanding
/// of ownership semantics.
///
/// ### Why is this bad?
/// It isn't bad in general. But in some contexts it can be desirable
/// because it increases ownership hints in the code, and will guard against some changes
/// ### Why restrict this?
/// It increases ownership hints in the code, and will guard against some changes
/// in ownership.
///
/// ### Example

8
clippy_lints/src/pub_use.rs
View File

@ -5,13 +5,11 @@ use rustc_session::declare_lint_pass;
declare_clippy_lint! {
/// ### What it does
///
/// Restricts the usage of `pub use ...`
///
/// ### Why is this bad?
///
/// `pub use` is usually fine, but a project may wish to limit `pub use` instances to prevent
/// unintentional exports or to encourage placing exported items directly in public modules
/// ### Why restrict this?
/// A project may wish to limit `pub use` instances to prevent
/// unintentional exports, or to encourage placing exported items directly in public modules.
///
/// ### Example
/// ```no_run

2
clippy_lints/src/question_mark_used.rs
View File

@ -9,7 +9,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for expressions that use the question mark operator and rejects them.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Sometimes code wants to avoid the question mark operator because for instance a local
/// block requires a macro to re-throw errors to attach additional information to the
/// error.

6
clippy_lints/src/raw_strings.rs
View File

@ -15,8 +15,10 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for raw string literals where a string literal can be used instead.
///
/// ### Why is this bad?
/// It's just unnecessary, but there are many cases where using a raw string literal is more
/// ### Why restrict this?
/// For consistent style by using simpler string literals whenever possible.
///
/// However, there are many cases where using a raw string literal is more
/// idiomatic than a string literal, so it's opt-in.
///
/// ### Example

2
clippy_lints/src/redundant_slicing.rs
View File

@ -46,7 +46,7 @@ declare_clippy_lint! {
/// Checks for slicing expressions which are equivalent to dereferencing the
/// value.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Some people may prefer to dereference rather than slice.
///
/// ### Example

2
clippy_lints/src/redundant_type_annotations.rs
View File

@ -11,7 +11,7 @@ declare_clippy_lint! {
/// ### What it does
/// Warns about needless / redundant type annotations.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Code without type annotations is shorter and in most cases
/// more idiomatic and easier to modify.
///

4
clippy_lints/src/ref_patterns.rs
View File

@ -6,9 +6,11 @@ use rustc_session::declare_lint_pass;
declare_clippy_lint! {
/// ### What it does
/// Checks for usages of the `ref` keyword.
/// ### Why is this bad?
///
/// ### Why restrict this?
/// The `ref` keyword can be confusing for people unfamiliar with it, and often
/// it is more concise to use `&` instead.
///
/// ### Example
/// ```no_run
/// let opt = Some(5);

2
clippy_lints/src/same_name_method.rs
View File

@ -14,7 +14,7 @@ declare_clippy_lint! {
/// It lints if a struct has two methods with the same name:
/// one from a trait, another not from trait.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Confusing.
///
/// ### Example

6
clippy_lints/src/semicolon_block.rs
View File

@ -11,8 +11,7 @@ declare_clippy_lint! {
/// Suggests moving the semicolon after a block to the inside of the block, after its last
/// expression.
///
/// ### Why is this bad?
///
/// ### Why restrict this?
/// For consistency it's best to have the semicolon inside/outside the block. Either way is fine
/// and this lint suggests inside the block.
/// Take a look at `semicolon_outside_block` for the other alternative.
@ -40,8 +39,7 @@ declare_clippy_lint! {
///
/// Suggests moving the semicolon from a block's final expression outside of the block.
///
/// ### Why is this bad?
///
/// ### Why restrict this?
/// For consistency it's best to have the semicolon inside/outside the block. Either way is fine
/// and this lint suggests outside the block.
/// Take a look at `semicolon_inside_block` for the other alternative.

26
clippy_lints/src/shadow.rs
View File

@ -15,10 +15,10 @@ declare_clippy_lint! {
/// Checks for bindings that shadow other bindings already in
/// scope, while just changing reference level or mutability.
///
/// ### Why is this bad?
/// Not much, in fact it's a very common pattern in Rust
/// code. Still, some may opt to avoid it in their code base, they can set this
/// lint to `Warn`.
/// ### Why restrict this?
/// To require that what are formally distinct variables be given distinct names.
///
/// See also `shadow_reuse` and `shadow_unrelated` for other restrictions on shadowing.
///
/// ### Example
/// ```no_run
@ -42,12 +42,13 @@ declare_clippy_lint! {
/// Checks for bindings that shadow other bindings already in
/// scope, while reusing the original value.
///
/// ### Why is this bad?
/// Not too much, in fact it's a common pattern in Rust
/// code. Still, some argue that name shadowing like this hurts readability,
/// ### Why restrict this?
/// Some argue that name shadowing like this hurts readability,
/// because a value may be bound to different things depending on position in
/// the code.
///
/// See also `shadow_same` and `shadow_unrelated` for other restrictions on shadowing.
///
/// ### Example
/// ```no_run
/// let x = 2;
@ -70,11 +71,14 @@ declare_clippy_lint! {
/// scope, either without an initialization or with one that does not even use
/// the original value.
///
/// ### Why is this bad?
/// Name shadowing can hurt readability, especially in
/// ### Why restrict this?
/// Shadowing a binding with a closely related one is part of idiomatic Rust,
/// but shadowing a binding by accident with an unrelated one may indicate a mistake.
///
/// Additionally, name shadowing in general can hurt readability, especially in
/// large code bases, because it is easy to lose track of the active binding at
/// any place in the code. This can be alleviated by either giving more specific
/// names to bindings or introducing more scopes to contain the bindings.
/// any place in the code. If linting against all shadowing is desired, you may wish
/// to use the `shadow_same` and `shadow_reuse` lints as well.
///
/// ### Example
/// ```no_run

19
clippy_lints/src/single_call_fn.rs
View File

@ -13,13 +13,20 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for functions that are only used once. Does not lint tests.
///
/// ### Why is this bad?
/// It's usually not, splitting a function into multiple parts often improves readability and in
/// the case of generics, can prevent the compiler from duplicating the function dozens of
/// time; instead, only duplicating a thunk. But this can prevent segmentation across a
/// codebase, where many small functions are used only once.
/// ### Why restrict this?
/// If a function is only used once (perhaps because it used to be used more widely),
/// then the code could be simplified by moving that function's code into its caller.
///
/// Note: If this lint is used, prepare to allow this a lot.
/// However, there are reasons not to do this everywhere:
///
/// * Splitting a large function into multiple parts often improves readability
/// by giving names to its parts.
/// * A function’s signature might serve a necessary purpose, such as constraining
/// the type of a closure passed to it.
/// * Generic functions might call non-generic functions to reduce duplication
/// in the produced machine code.
///
/// If this lint is used, prepare to `#[allow]` it a lot.
///
/// ### Example
/// ```no_run

5
clippy_lints/src/single_char_lifetime_names.rs
View File

@ -9,11 +9,10 @@ declare_clippy_lint! {
/// Checks for lifetimes with names which are one character
/// long.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// A single character is likely not enough to express the
/// purpose of a lifetime. Using a longer name can make code
/// easier to understand, especially for those who are new to
/// Rust.
/// easier to understand.
///
/// ### Known problems
/// Rust programmers and learning resources tend to use single

12
clippy_lints/src/std_instead_of_core.rs
View File

@ -12,11 +12,9 @@ use rustc_span::{sym, Span};
declare_clippy_lint! {
/// ### What it does
///
/// Finds items imported through `std` when available through `core`.
///
/// ### Why is this bad?
///
/// ### Why restrict this?
/// Crates which have `no_std` compatibility may wish to ensure types are imported from core to ensure
/// disabling `std` does not cause the crate to fail to compile. This lint is also useful for crates
/// migrating to become `no_std` compatible.
@ -37,11 +35,9 @@ declare_clippy_lint! {
declare_clippy_lint! {
/// ### What it does
///
/// Finds items imported through `std` when available through `alloc`.
///
/// ### Why is this bad?
///
/// ### Why restrict this?
/// Crates which have `no_std` compatibility and require alloc may wish to ensure types are imported from
/// alloc to ensure disabling `std` does not cause the crate to fail to compile. This lint is also useful
/// for crates migrating to become `no_std` compatible.
@ -63,11 +59,9 @@ declare_clippy_lint! {
declare_clippy_lint! {
/// ### What it does
///
/// Finds items imported through `alloc` when available through `core`.
///
/// ### Why is this bad?
///
/// ### Why restrict this?
/// Crates which have `no_std` compatibility and may optionally require alloc may wish to ensure types are
/// imported from core to ensure disabling `alloc` does not cause the crate to fail to compile. This lint
/// is also useful for crates migrating to become `no_std` compatible.

19
clippy_lints/src/strings.rs
View File

@ -45,10 +45,10 @@ declare_clippy_lint! {
/// `String`, but only if [`string_add_assign`](#string_add_assign) does *not*
/// match.
///
/// ### Why is this bad?
/// It's not bad in and of itself. However, this particular
/// ### Why restrict this?
/// This particular
/// `Add` implementation is asymmetric (the other operand need not be `String`,
/// but `x` does), while addition as mathematically defined is symmetric, also
/// but `x` does), while addition as mathematically defined is symmetric, and
/// the `String::push_str(_)` function is a perfectly good replacement.
/// Therefore, some dislike it and wish not to have it in their code.
///
@ -123,7 +123,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for slice operations on strings
///
/// ### Why is this bad?
/// ### Why restrict this?
/// UTF-8 characters span multiple bytes, and it is easy to inadvertently confuse character
/// counts and string indices. This may lead to panics, and should warrant some test cases
/// containing wide UTF-8 characters. This lint is most useful in code that should avoid
@ -364,10 +364,10 @@ declare_clippy_lint! {
/// ### What it does
/// This lint checks for `.to_string()` method calls on values of type `&str`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// The `to_string` method is also used on other types to convert them to a string.
/// When called on a `&str` it turns the `&str` into the owned variant `String`, which can be better
/// expressed with `.to_owned()`.
/// When called on a `&str` it turns the `&str` into the owned variant `String`, which can be
/// more specifically expressed with `.to_owned()`.
///
/// ### Example
/// ```no_run
@ -415,9 +415,10 @@ declare_clippy_lint! {
/// ### What it does
/// This lint checks for `.to_string()` method calls on values of type `String`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// The `to_string` method is also used on other types to convert them to a string.
/// When called on a `String` it only clones the `String`, which can be better expressed with `.clone()`.
/// When called on a `String` it only clones the `String`, which can be more specifically
/// expressed with `.clone()`.
///
/// ### Example
/// ```no_run

4
clippy_lints/src/suspicious_xor_used_as_pow.rs
View File

@ -11,8 +11,10 @@ use rustc_session::declare_lint_pass;
declare_clippy_lint! {
/// ### What it does
/// Warns for a Bitwise XOR (`^`) operator being probably confused as a powering. It will not trigger if any of the numbers are not in decimal.
/// ### Why is this bad?
///
/// ### Why restrict this?
/// It's most probably a typo and may lead to unexpected behaviours.
///
/// ### Example
/// ```no_run
/// let x = 3_i32 ^ 4_i32;

4
clippy_lints/src/tests_outside_test_module.rs
View File

@ -11,9 +11,11 @@ declare_clippy_lint! {
/// ### What it does
/// Triggers when a testing function (marked with the `#[test]` attribute) isn't inside a testing module
/// (marked with `#[cfg(test)]`).
/// ### Why is this bad?
///
/// ### Why restrict this?
/// The idiomatic (and more performant) way of writing tests is inside a testing module (flagged with `#[cfg(test)]`),
/// having test functions outside of this module is confusing and may lead to them being "hidden".
///
/// ### Example
/// ```no_run
/// #[test]

4
clippy_lints/src/types/mod.rs
View File

@ -217,7 +217,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `Rc<T>` and `Arc<T>` when `T` is a mutable buffer type such as `String` or `Vec`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Expressions such as `Rc<String>` usually have no advantage over `Rc<str>`, since
/// it is larger and involves an extra level of indirection, and doesn't implement `Borrow<str>`.
///
@ -274,7 +274,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `Rc<Mutex<T>>`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// `Rc` is used in single thread and `Mutex` is used in multi thread.
/// Consider using `Rc<RefCell<T>>` in single thread or `Arc<Mutex<T>>` in multi thread.
///

9
clippy_lints/src/undocumented_unsafe_blocks.rs
View File

@ -38,10 +38,9 @@ declare_clippy_lint! {
/// );
/// ```
///
/// ### Why is this bad?
/// Undocumented unsafe blocks and impls can make it difficult to
/// read and maintain code, as well as uncover unsoundness
/// and bugs.
/// ### Why restrict this?
/// Undocumented unsafe blocks and impls can make it difficult to read and maintain code.
/// Writing out the safety justification may help in discovering unsoundness or bugs.
///
/// ### Example
/// ```no_run
@ -67,7 +66,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for `// SAFETY: ` comments on safe code.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Safe code has no safety requirements, so there is no need to
/// describe safety invariants.
///

2
clippy_lints/src/unicode.rs
View File

@ -31,7 +31,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for non-ASCII characters in string and char literals.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Yeah, we know, the 90's called and wanted their charset
/// back. Even so, there still are editors and other programs out there that
/// don't work well with Unicode. So if the code is meant to be used

2
clippy_lints/src/unnecessary_self_imports.rs
View File

@ -9,7 +9,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for imports ending in `::{self}`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// In most cases, this can be written much more cleanly by omitting `::{self}`.
///
/// ### Known problems

6
clippy_lints/src/unwrap_in_result.rs
View File

@ -13,8 +13,10 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for functions of type `Result` that contain `expect()` or `unwrap()`
///
/// ### Why is this bad?
/// These functions promote recoverable errors to non-recoverable errors which may be undesirable in code bases which wish to avoid panics.
/// ### Why restrict this?
/// These functions promote recoverable errors to non-recoverable errors,
/// which may be undesirable in code bases which wish to avoid panics,
/// or be a bug in the specific function.
///
/// ### Known problems
/// This can cause false positives in functions that handle both recoverable and non recoverable errors.

4
clippy_lints/src/visibility.rs
View File

@ -32,7 +32,7 @@ declare_clippy_lint! {
/// ### What it does
/// Checks for usage of `pub(<loc>)` with `in`.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Consistency. Use it or don't, just be consistent about it.
///
/// Also see the `pub_without_shorthand` lint for an alternative.
@ -57,7 +57,7 @@ declare_clippy_lint! {
/// Note: As you cannot write a module's path in `pub(<loc>)`, this will only trigger on
/// `pub(super)` and the like.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// Consistency. Use it or don't, just be consistent about it.
///
/// Also see the `pub_with_shorthand` lint for an alternative.

13
clippy_lints/src/write.rs
View File

@ -66,7 +66,7 @@ declare_clippy_lint! {
/// Checks for printing on *stdout*. The purpose of this lint
/// is to catch debugging remnants.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// People often print on *stdout* while debugging an
/// application and might forget to remove those prints afterward.
///
@ -88,7 +88,7 @@ declare_clippy_lint! {
/// Checks for printing on *stderr*. The purpose of this lint
/// is to catch debugging remnants.
///
/// ### Why is this bad?
/// ### Why restrict this?
/// People often print on *stderr* while debugging an
/// application and might forget to remove those prints afterward.
///
@ -110,15 +110,18 @@ declare_clippy_lint! {
/// Checks for usage of `Debug` formatting. The purpose of this
/// lint is to catch debugging remnants.
///
/// ### Why is this bad?
/// The purpose of the `Debug` trait is to facilitate
/// debugging Rust code. It should not be used in user-facing output.
/// ### Why restrict this?
/// The purpose of the `Debug` trait is to facilitate debugging Rust code,
/// and [no guarantees are made about its output][stability].
/// It should not be used in user-facing output.
///
/// ### Example
/// ```no_run
/// # let foo = "bar";
/// println!("{:?}", foo);
/// ```
///
/// [stability]: https://doc.rust-lang.org/stable/std/fmt/trait.Debug.html#stability
#[clippy::version = "pre 1.29.0"]
pub USE_DEBUG,
restriction,