Auto merge of #76549 - ehuss:lints-comments, r=wesleywiser

Auto-generate lint documentation.

This adds a tool which will generate the lint documentation in the rustc book automatically. This is motivated by keeping the documentation up-to-date, and consistently formatted. It also ensures the examples are correct and that they actually generate the expected lint. The lint groups table is also auto-generated. See rust-lang/compiler-team#349 for the original proposal.

An outline of how this works:
- The `declare_lint!` macro now accepts a doc comment where the documentation is written. This is inspired by how clippy works.
- A new tool `src/tools/lint-docs` scrapes the documentation and adds it to the rustc book during the build.
    - It runs each example and verifies its output and embeds the output in the book.
    - It does a few formatting checks.
    - It verifies that every lint is documented.
- Groups are collected from `rustc -W help`.

I updated the documentation for all the missing lints. I have also added an "Explanation" section to each lint providing a reason for the lint and suggestions on how to resolve it.

This can lead towards a future enhancement of possibly showing these docs via the `--explain` flag to make them easily accessible and discoverable.

Cargo.lock

@@ -1677,6 +1677,15 @@ version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8dd5a6d5999d9907cda8ed67bbd137d3af8085216c2ac62de5be860bd41f304a"
 
+[[package]]
+name = "lint-docs"
+version = "0.1.0"
+dependencies = [
+ "serde_json",
+ "tempfile",
+ "walkdir",
+]
+
 [[package]]
 name = "lock_api"
 version = "0.3.4"

Cargo.toml

@@ -9,6 +9,7 @@ members = [
   "src/tools/compiletest",
   "src/tools/error_index_generator",
   "src/tools/linkchecker",
+  "src/tools/lint-docs",
   "src/tools/rustbook",
   "src/tools/unstable-book-gen",
   "src/tools/tidy",

compiler/rustc_lint/src/array_into_iter.rs

@@ -7,6 +7,31 @@ use rustc_session::lint::FutureIncompatibleInfo;
 use rustc_span::symbol::sym;
 
 declare_lint! {
+    /// The `array_into_iter` lint detects calling `into_iter` on arrays.
+    ///
+    /// ### Example
+    ///
+    /// ```rust
+    /// # #![allow(unused)]
+    /// [1, 2, 3].into_iter().for_each(|n| { *n; });
+    /// ```
+    ///
+    /// {{produces}}
+    ///
+    /// ### Explanation
+    ///
+    /// In the future, it is planned to add an `IntoIter` implementation for
+    /// arrays such that it will iterate over *values* of the array instead of
+    /// references. Due to how method resolution works, this will change
+    /// existing code that uses `into_iter` on arrays. The solution to avoid
+    /// this warning is to use `iter()` instead of `into_iter()`.
+    ///
+    /// This is a [future-incompatible] lint to transition this to a hard error
+    /// in the future. See [issue #66145] for more details and a more thorough
+    /// description of the lint.
+    ///
+    /// [issue #66145]: https://github.com/rust-lang/rust/issues/66145
+    /// [future-incompatible]: ../index.md#future-incompatible-lints
     pub ARRAY_INTO_ITER,
     Warn,
     "detects calling `into_iter` on arrays",