From 0e42282ed5830ea014454130e04cc6e5d72955c9 Mon Sep 17 00:00:00 2001 From: flip1995 Date: Sun, 17 Apr 2022 15:45:44 +0200 Subject: [PATCH] Book: Write lint group descriptions This removes the empty separate files for the different groups and adds a single file giving short explanations for each group and what to expect from those groups. --- book/src/SUMMARY.md | 10 +--- book/src/lints.md | 105 ++++++++++++++++++++++++++++++++++ book/src/lints/README.md | 1 - book/src/lints/cargo.md | 0 book/src/lints/complexity.md | 0 book/src/lints/correctness.md | 0 book/src/lints/deprecated.md | 0 book/src/lints/nursery.md | 0 book/src/lints/pedantic.md | 0 book/src/lints/perf.md | 0 book/src/lints/restriction.md | 0 book/src/lints/style.md | 0 12 files changed, 106 insertions(+), 10 deletions(-) create mode 100644 book/src/lints.md delete mode 100644 book/src/lints/README.md delete mode 100644 book/src/lints/cargo.md delete mode 100644 book/src/lints/complexity.md delete mode 100644 book/src/lints/correctness.md delete mode 100644 book/src/lints/deprecated.md delete mode 100644 book/src/lints/nursery.md delete mode 100644 book/src/lints/pedantic.md delete mode 100644 book/src/lints/perf.md delete mode 100644 book/src/lints/restriction.md delete mode 100644 book/src/lints/style.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index db937f95d22..95bdde7281c 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -5,15 +5,7 @@ - [Installation](installation.md) - [Usage](usage.md) - [Configuration](configuration.md) -- [Clippy's Lints](lints/README.md) - - [Correctness]() - - [Suspicious]() - - [Style]() - - [Complexity]() - - [Perf]() - - [Pendantic]() - - [Nursery]() - - [Cargo]() +- [Clippy's Lints](lints.md) - [Continuous Integration](continuous_integration/README.md) - [Travis CI](continuous_integration/travis.md) - [GitHub Actions](continuous_integration/github_actions.md) diff --git a/book/src/lints.md b/book/src/lints.md new file mode 100644 index 00000000000..35e30960b56 --- /dev/null +++ b/book/src/lints.md @@ -0,0 +1,105 @@ +# Clippy's Lints + +Clippy offers a bunch of additional lints, to help its users write more correct +and idiomatic Rust code. A full list of all lints, that can be filtered by +category, lint level or keywords, can be found in the [Clippy lint +documentation]. + +This chapter will give an overview of the different lint categories, which kind +of lints they offer and recommended actions when you should see a lint out of +that category. For examples, see the [Clippy lint documentation] and filter by +category. + +The different lint groups were defined in the [Clippy 1.0 RFC]. + +## Correctness + +The `clippy::correctness` group is the only lint group in Clippy which lints are +deny-by-default and abort the compilation when triggered. This is for good +reason: If you see a `correctness` lint, it means that your code is outright +wrong or useless and you should try to fix it. + +Lints in this category are carefully picked and should be free of false +positives. So just `#[allow]`ing those lints is not recommended. + +## Suspicious + +The `clippy::suspicious` group is similar to the correctness lints in that it +contains lints that trigger on code that is really _sus_ and should be fixed. As +opposed to correctness lints, it might be possible that the linted code is +intentionally written like it is. + +It is still recommended to fix code that is linted by lints out of this group +instead of `#[allow]`ing the lint. In case you intentionally have written code +that offends the lint you should specifically and locally `#[allow]` the lint +and add give a reason why the code is correct as written. + +## Complexity + +The `clippy::complexity` group offers lints that give you suggestions on how to +simplify your code. It mostly focuses on code that can be written in a shorter +and more readable way, while preserving the semantics. + +If you should see a complexity lint, it usually means that you can remove or +replace some code and it is recommended to do so. However, if you need the more +complex code for some expressiveness reason, it is recommended to allow +complexity lints on a case-by-case basis. + +## Perf + +The `clippy::perf` group gives you suggestions on how you can increase the +performance of your code. Those lints are mostly about code that the compiler +can't trivially optimize, but has to be written in a slightly different way to +make the optimizer's job easier. + +Perf lints are usually easy to apply and it is recommended to do so. + +## Style + +The `clippy::style` group is mostly about writing idiomatic code. Because style +is subjective, this lint group is the most opinionated warn-by-default group in +Clippy. + +If you see a style lint, applying the suggestion usually makes your code more +readable and idiomatic. But because we know that this is opinionated, feel free +to sprinkle `#[allow]`s for style lints in your code or `#![allow]` a style lint +on your whole crate if you disagree with the suggested style completely. + +## Pedantic + +The `clippy::pedantic` group makes Clippy even more _pedantic_. You can enable +the whole group with `#![warn(clippy::pedantic)]` in the `lib.rs`/`main.rs` of +your crate. This lint group is for Clippy power users that want an in depth +check of their code. + +> _Note:_ Instead of enabling the whole group (like Clippy itself does), you may +> want to cherry-pick lints out of the pedantic group. + +If you enable this group, expect to also use `#[allow]` attributes generously +throughout your code. Lints in this group are designed to be pedantic and false +positives sometimes are intentional in order to prevent false negatives. + +## Restriction + +The `clippy::restriction` group contains lints that will _restrict_ you from +using certain parts of the Rust language. It is **not** recommended to enable +the whole group, but rather cherry-pick lints that are useful for your code base +and your use case. + +> _Note:_ Clippy will produce a warning if it finds a +> `#![warn(clippy::restriction)]` attribute in your code! + +Lints from this group will restrict you in some way. If you enable a restriction +lint for your crate it is recommended to also fix code that this lint triggers +on. However, those lints are really strict by design and you might want to +`#[allow]` them in some special cases, with a comment justifying that. + +## Cargo + +The `clippy::cargo` group gives you suggestions on how to improve your +`Cargo.toml` file. This might be especially interesting if you want to publish +your crate and are not sure if you have all useful information in your +`Cargo.toml`. + +[Clippy lint documentation]: https://rust-lang.github.io/rust-clippy/ +[Clippy 1.0 RFC]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#lint-audit-and-categories diff --git a/book/src/lints/README.md b/book/src/lints/README.md deleted file mode 100644 index a2777e8f4d5..00000000000 --- a/book/src/lints/README.md +++ /dev/null @@ -1 +0,0 @@ -# Clippy's Lints diff --git a/book/src/lints/cargo.md b/book/src/lints/cargo.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/book/src/lints/complexity.md b/book/src/lints/complexity.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/book/src/lints/correctness.md b/book/src/lints/correctness.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/book/src/lints/deprecated.md b/book/src/lints/deprecated.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/book/src/lints/nursery.md b/book/src/lints/nursery.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/book/src/lints/pedantic.md b/book/src/lints/pedantic.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/book/src/lints/perf.md b/book/src/lints/perf.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/book/src/lints/restriction.md b/book/src/lints/restriction.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/book/src/lints/style.md b/book/src/lints/style.md deleted file mode 100644 index e69de29bb2d..00000000000