Initial commit for the Clippy Book

Author: joshrotenberg

.gitignore

@@ -39,3 +39,6 @@ helper.txt
 *.iml
 .vscode
 .idea
+
+# mdbook generated output
+/book/book

book/README.md

@@ -0,0 +1,4 @@
+# Clippy Book
+
+This is the source for the Clippy Book. See the
+[book](src/infrastructure/book.md) for more information.

book/book.toml

@@ -0,0 +1,28 @@
+[book]
+authors = ["The Rust Clippy Developers"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Clippy Documentation"
+
+[rust]
+edition = "2018"
+
+[output.html]
+edit-url-template = "https://github.com/rust-lang/rust-clippy/edit/master/book/{path}"
+git-repository-url = "https://github.com/rust-lang/rust-clippy/tree/master/book"
+mathjax-support = true
+site-url = "/rust-clippy/"
+
+[output.html.playground]
+editable = true
+line-numbers = true
+
+[output.html.search]
+boost-hierarchy = 2
+boost-paragraph = 1
+boost-title = 2
+expand = true
+heading-split-level = 2
+limit-results = 20
+use-boolean-and = true

book/src/README.md

@@ -0,0 +1,34 @@
+# Clippy
+
+[![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)
+[![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/clippy.svg)](#license)
+
+A collection of lints to catch common mistakes and improve your
+[Rust](https://github.com/rust-lang/rust) code.
+
+[There are over 500 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html)
+
+Lints are divided into categories, each with a default [lint
+level](https://doc.rust-lang.org/rustc/lints/levels.html). You can choose how
+much Clippy is supposed to ~~annoy~~ help you by changing the lint level by
+category.
+
+| Category              | Description                                                                         | Default level |
+| --------------------- | ----------------------------------------------------------------------------------- | ------------- |
+| `clippy::all`         | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** |
+| `clippy::correctness` | code that is outright wrong or useless                                              | **deny**      |
+| `clippy::suspicious`  | code that is most likely wrong or useless                                           | **warn**      |
+| `clippy::complexity`  | code that does something simple but in a complex way                                | **warn**      |
+| `clippy::perf`        | code that can be written to run faster                                              | **warn**      |
+| `clippy::style`       | code that should be written in a more idiomatic way                                 | **warn**      |
+| `clippy::pedantic`    | lints which are rather strict or might have false positives                         | allow         |
+| `clippy::nursery`     | new lints that are still under development                                          | allow         |
+| `clippy::cargo`       | lints for the cargo manifest                                                        | allow         |                                   | allow         |
+
+More to come, please [file an
+issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas!
+
+The [lint list](https://rust-lang.github.io/rust-clippy/master/index.html) also
+contains "restriction lints", which are for things which are usually not
+considered "bad", but may be useful to turn on in specific cases. These should
+be used very selectively, if at all.

book/src/SUMMARY.md

@@ -0,0 +1,26 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Installation and Usage](installation_and_usage.md)
+- [Configuration](configuration.md)
+- [Clippy's Lints](lints/README.md)
+    - [Correctness]()
+    - [Suspicious]()
+    - [Style]()
+    - [Complexity]()
+    - [Perf]()
+    - [Pendantic]()
+    - [Nursery]()
+    - [Cargo]()
+- [Development](development/README.md)
+    - [Basics](development/basics.md)
+    - [Adding Lints](development/adding_lints.md)
+    - [Common Tools](development/common_tools_writing_lints.md)
+- [Infrastructure](infrastructure/README.md)
+    - [Backporting Changes](infrastructure/backport.md)
+    - [Updating the Changelog](infrastructure/changelog_update.md)
+    - [Release a New Version](infrastructure/release.md)
+    - [The Clippy Book](infrastructure/book.md)
+- [Roadmap](roadmap/README.md)
+    - [2021](roadmap/2021.md)

book/src/configuration.md

@@ -0,0 +1,92 @@
+# Configuring Clippy
+
+> **Note:** The configuration file is unstable and may be deprecated in the future.
+
+Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a
+basic `variable = value` mapping eg.
+
+```toml
+avoid-breaking-exported-api = false
+blacklisted-names = ["toto", "tata", "titi"]
+cognitive-complexity-threshold = 30
+```
+
+See the [list of lints](https://rust-lang.github.io/rust-clippy/master/index.html) for more information about which
+lints can be configured and the meaning of the variables.
+
+To deactivate the "for further information visit *lint-link*" message you can define the `CLIPPY_DISABLE_DOCS_LINKS`
+environment variable.
+
+### Allowing/denying lints
+
+You can add options to your code to `allow`/`warn`/`deny` Clippy lints:
+
+* the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`)
+
+* all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`,
+  `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive lints prone to false
+  positives.
+
+* only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.)
+
+* `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc.
+
+Note: `allow` means to suppress the lint for your code. With `warn` the lint will only emit a warning, while with `deny`
+the lint will emit an error, when triggering for your code. An error causes clippy to exit with an error code, so is
+useful in scripts like CI/CD.
+
+If you do not want to include your lint levels in your code, you can globally enable/disable lints by passing extra
+flags to Clippy during the run:
+
+To allow `lint_name`, run
+
+```terminal
+cargo clippy -- -A clippy::lint_name
+```
+
+And to warn on `lint_name`, run
+
+```terminal
+cargo clippy -- -W clippy::lint_name
+```
+
+This also works with lint groups. For example you can run Clippy with warnings for all lints enabled:
+
+```terminal
+cargo clippy -- -W clippy::pedantic
+```
+
+If you care only about a single lint, you can allow all others and then explicitly warn on the lint(s) you are
+interested in:
+
+```terminal
+cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::...
+```
+
+### Specifying the minimum supported Rust version
+
+Projects that intend to support old versions of Rust can disable lints pertaining to newer features by specifying the
+minimum supported Rust version (MSRV) in the clippy configuration file.
+
+```toml
+msrv = "1.30.0"
+```
+
+The MSRV can also be specified as an inner attribute, like below.
+
+```rust
+#![feature(custom_inner_attributes)]
+#![clippy::msrv = "1.30.0"]
+
+fn main() {
+    ...
+}
+```
+
+You can also omit the patch version when specifying the MSRV, so `msrv = 1.30`
+is equivalent to `msrv = 1.30.0`.
+
+Note: `custom_inner_attributes` is an unstable feature so it has to be enabled explicitly.
+
+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

@@ -0,0 +1 @@
+# Clippy Development