Skip to content

Commit 25e5fae

Browse files
joshrotenbergjoshrotenberg
committed
clippy book
clippy book clippy book base guide add a guide README.md move guide to book move guide to book add infra chapters add roadmap section
1 parent 7c9da3c commit 25e5fae

27 files changed

+1819
-0
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,6 @@ helper.txt
3838
*.iml
3939
.vscode
4040
.idea
41+
42+
# mdbook generated output
43+
/book/book

‎book/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Clippy Guide
2+
3+
This is the source for the [Clippy Guide] using [mdbook].
4+
5+
6+
[Clippy Guide]:
7+
[mdbook]: https://github.com/rust-lang/mdbook

‎book/book.toml

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
[book]
2+
authors = ["Josh Rotenberg"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "Clippy Documentation"
7+
8+
[rust]
9+
edition = "2018"
10+
11+
[output.html]
12+
edit-url-template = "https://github.com/rust-lang/rust-clippy/edit/master/guide/{path}"
13+
git-repository-url = "https://github.com/rust-lang/rust-clippy/tree/master/guide"
14+
mathjax-support = true
15+
site-url = "/rust-clippy/"
16+
17+
[output.html.playground]
18+
editable = true
19+
line-numbers = true
20+
21+
[output.html.search]
22+
boost-hierarchy = 2
23+
boost-paragraph = 1
24+
boost-title = 2
25+
expand = true
26+
heading-split-level = 2
27+
limit-results = 20
28+
use-boolean-and = true

‎book/src/README.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Introduction
2+
3+
[![Clippy Test](https://github.com/rust-lang/rust-clippy/workflows/Clippy%20Test/badge.svg?branch=auto&event=push)](https://github.com/rust-lang/rust-clippy/actions?query=workflow%3A%22Clippy+Test%22+event%3Apush+branch%3Aauto)
4+
[![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/clippy.svg)](#license)
5+
6+
A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code.
7+
8+
[There are over 450 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html)
9+
10+
Lints are divided into categories, each with a default [lint level](https://doc.rust-lang.org/rustc/lints/levels.html).
11+
You can choose how much Clippy is supposed to ~~annoy~~ help you by changing the lint level by category.
12+
13+
| Category | Description | Default level |
14+
| --------------------- | ----------------------------------------------------------------------- | ------------- |
15+
| `clippy::all` | all lints that are on by default (correctness, style, complexity, perf) | **warn/deny** |
16+
| `clippy::correctness` | code that is outright wrong or very useless | **deny** |
17+
| `clippy::style` | code that should be written in a more idiomatic way | **warn** |
18+
| `clippy::complexity` | code that does something simple but in a complex way | **warn** |
19+
| `clippy::perf` | code that can be written to run faster | **warn** |
20+
| `clippy::pedantic` | lints which are rather strict or might have false positives | allow |
21+
| `clippy::nursery` | new lints that are still under development | allow |
22+
| `clippy::cargo` | lints for the cargo manifest | allow |
23+
24+
More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas!
25+
26+
The [lint list](https://rust-lang.github.io/rust-clippy/master/index.html) also contains "restriction lints", which are
27+
for things which are usually not considered "bad", but may be useful to turn on in specific cases. These should be used
28+
very selectively, if at all.

‎book/src/SUMMARY.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Summary
2+
3+
[Introduction](README.md)
4+
5+
- [Installation and Usage](installation_and_usage.md)
6+
- [Configuration](configuration.md)
7+
- [Clippy's Lints](lints/README.md)
8+
- [Cargo]()
9+
- [Complexity]()
10+
- [Correctness]()
11+
- [Pedantic]()
12+
- [Perf]()
13+
- [Restriction]()
14+
- [Style]()
15+
- [Deprecated]()
16+
- [Nursery]()
17+
- [Development](development/README.md)
18+
- [Basics](development/basics.md)
19+
- [Adding Lints](development/adding_lints.md)
20+
- [Common Tools](development/common_tools_writing_lints.md)
21+
- [Infrastructure](infrastructure/README.md)
22+
- [Backporting Changes](infrastructure/backport.md)
23+
- [Updating the Changelog](infrastructure/changelog_update.md)
24+
- [Release a New Version](infrastructure/release.md)
25+
- [Roadmap](roadmap/README.md)
26+
- [2021](roadmap/2021.md)

‎book/src/configuration.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Configuring Clippy
2+
3+
Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable =
4+
value` mapping eg.
5+
6+
```toml
7+
avoid-breaking-exported-api = false
8+
blacklisted-names = ["toto", "tata", "titi"]
9+
cognitive-complexity-threshold = 30
10+
```
11+
12+
See the [list of lints](https://rust-lang.github.io/rust-clippy/master/index.html) for more information about which
13+
lints can be configured and the meaning of the variables.
14+
15+
To deactivate the “for further information visit *lint-link*” message you can
16+
define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
17+
18+
### Allowing/denying lints
19+
20+
You can add options to your code to `allow`/`warn`/`deny` Clippy lints:
21+
22+
* the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`)
23+
24+
* all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`,
25+
`#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive
26+
lints prone to false positives.
27+
28+
* only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.)
29+
30+
* `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc.
31+
32+
Note: `allow` means to suppress the lint for your code. With `warn` the lint
33+
will only emit a warning, while with `deny` the lint will emit an error, when
34+
triggering for your code. An error causes clippy to exit with an error code, so
35+
is useful in scripts like CI/CD.
36+
37+
If you do not want to include your lint levels in your code, you can globally
38+
enable/disable lints by passing extra flags to Clippy during the run:
39+
40+
To allow `lint_name`, run
41+
42+
```terminal
43+
cargo clippy -- -A clippy::lint_name
44+
```
45+
46+
And to warn on `lint_name`, run
47+
48+
```terminal
49+
cargo clippy -- -W clippy::lint_name
50+
```
51+
52+
This also works with lint groups. For example you
53+
can run Clippy with warnings for all lints enabled:
54+
```terminal
55+
cargo clippy -- -W clippy::pedantic
56+
```
57+
58+
If you care only about a single lint, you can allow all others and then explicitly warn on
59+
the lint(s) you are interested in:
60+
```terminal
61+
cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::...
62+
```
63+
64+
### Specifying the minimum supported Rust version
65+
66+
Projects that intend to support old versions of Rust can disable lints pertaining to newer features by
67+
specifying the minimum supported Rust version (MSRV) in the clippy configuration file.
68+
69+
```toml
70+
msrv = "1.30.0"
71+
```
72+
73+
The MSRV can also be specified as an inner attribute, like below.
74+
75+
```rust
76+
#![feature(custom_inner_attributes)]
77+
#![clippy::msrv = "1.30.0"]
78+
79+
fn main() {
80+
...
81+
}
82+
```
83+
84+
You can also omit the patch version when specifying the MSRV, so `msrv = 1.30`
85+
is equivalent to `msrv = 1.30.0`.
86+
87+
Note: `custom_inner_attributes` is an unstable feature so it has to be enabled explicitly.
88+
89+
Lints that recognize this configuration option can be found [here](https://rust-lang.github.io/rust-clippy/master/index.html#msrv)

‎book/src/development/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Clippy Development

0 commit comments

Comments
 (0)