Add some docs around the lint store

Author: Mark-Simulacrum

src/SUMMARY.md

@@ -23,6 +23,7 @@
     - [Coding conventions](./conventions.md)
     - [crates.io Dependencies](./crates-io.md)
     - [Emitting Errors and other Diagnostics](diagnostics.md)
+        - [`LintStore`](./diagnostics/lintstore.md)
     - [ICE-breaker teams](ice-breaker/about.md)
         - [LLVM ICE-breakers](ice-breaker/llvm.md)
 - [Part 2: How rustc works](./part-2-intro.md)

src/diagnostics.md

@@ -171,11 +171,17 @@ crate.
 
 [builtin]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/index.html
 
-Each lint is defined as a `struct` that implements the `LintPass` `trait`. The
-trait implementation allows you to check certain syntactic constructs the
-linter walks the source code. You can then choose to emit lints in a very
-similar way to compile errors. Finally, you register the lint to actually get
-it to be run by the compiler by using the `declare_lint!` macro.
+Every lint is implemented via a `struct` that implements the `LintPass` `trait`
+(you also implement one of the more specific lint pass traits, either
+`EarlyLintPass` or `LateLintPass`).  The trait implementation allows you to
+check certain syntactic constructs the linter walks the source code. You can
+then choose to emit lints in a very similar way to compile errors.
+
+You also declare the metadata of a particular lint via the `declare_lint!`
+macro. This includes the name, the default level, a short description, and some
+more details.
+
+Note that the lint and the lint pass must be registered with the compiler.
 
 For example, the following lint checks for uses
 of `while true { ... }` and suggests using `loop { ... }` instead.
@@ -196,11 +202,15 @@ declare_lint! {
 #[derive(Copy, Clone)]
 pub struct WhileTrue;
 
-impl LintPass for WhileTrue {
-    fn get_lints(&self) -> LintArray {
-        lint_array!(WHILE_TRUE)
-    }
-}
+// This declares a lint pass, providing a list of associated lints.  The
+// compiler currently doesn't use the associated lints directly (e.g., to not
+// run the pass or otherwise check that the pass emits the appropriate set of
+// lints). However, it's good to be accurate here as it's possible that we're
+// going to register the lints via the get_lints method on our lint pass (that
+// this macro generates).
+impl_lint_pass!(
+    WhileTrue => [WHILE_TRUE],
+);
 
 // LateLintPass has lots of methods. We only override the definition of
 // `check_expr` for this lint because that's all we need, but you could
@@ -242,9 +252,24 @@ declare_lint! {
 This makes the `ANONYMOUS_PARAMETERS` lint allow-by-default in the 2015 edition
 but warn-by-default in the 2018 edition.
 
-Lints that represent an incompatibility (i.e. error) in the upcoming edition
-should also be registered as `FutureIncompatibilityLint`s in
-[`register_builtins`][rbuiltins] function in [`rustc_lint::lib`][builtin].
+A future-incompatible lint should be declared with the `@future_incompatible`
+additional "field":
+
+```rust,ignore
+declare_lint! {
+    pub ANONYMOUS_PARAMETERS,
+    Allow,
+    "detects anonymous parameters",
+    @future_incompatible = FutureIncompatibleInfo {
+        reference: "issue #41686 <https://github.com/rust-lang/rust/issues/41686>",
+        edition: Some(Edition::Edition2018),
+    };
+}
+```
+
+If you need a combination of options that's not supported by the
+`declare_lint!` macro, you can always define your own static with a type of
+`&Lint` but this is currently linted against in the compiler tree.
 
 ### Lint Groups
 

src/diagnostics/lintstore.md

@@ -0,0 +1,40 @@
+# LintStore
+
+This page documents some of the machinery around lint registration and how we
+run lints in the compiler.
+
+The `LintStore` is the central piece of infrastructure, around which everything
+rotates. It's not available during the early parts of compilation (i.e., before
+TyCtxt) in most of the code, as we need to fill it in with all of the lints,
+which can only happen after plugin registration.
+
+We store essentially two separate things in the `LintStore`: a list of all known
+lints with associated metadata (default lint levels, notably), and the lint
+passes. We store constructors for the lint passes rather than the passes
+themselves, because lint passes often want to change state to track something
+in the code (so their methods take `&mut self`) and we want to avoid needing to
+synchronize access to the LintStore.
+
+For the most part, we currently only instantiate each lint pass once, though in
+the future we'll likely want more fine-grained linting to better support
+incremental compilation. We already have late module passes which are
+constructed per-module if the module changes in an incremental session.
+
+## Registration
+
+We must register both every lint and every lint pass into the `LintStore` for
+the code to work properly. This often is as simple as calling
+`register_lints(PassType::get_lints())` and then `register_late_pass(||
+Box::new(PassType))`.
+
+Within the compiler, for performance reasons, we usually do not register dozens
+of lint passes. Instead, we have a single lint pass of each variety
+(e.g. `BuiltinCombinedModuleLateLintPass`) which will internally call all of the
+individual lint passes; this is because then we get the benefits of static over
+dynamic dispatch for each of the (often empty) trait methods. Ideally, we'd not
+have to do this, since it certainly adds to the complexity of understanding the
+code. However, with the current type-erased lint store approach, it is
+beneficial to do so for performance reasons.
+
+New lints being added likely want to join one of the existing declarations like
+`late_lint_mod_passes` in `librustc_lint/lib.rs`.