Re-organize source code repr chapter

Author: BoxyUwU

src/SUMMARY.md

@@ -96,10 +96,6 @@
 # Source Code Representation
 
 - [Prologue](./part-3-intro.md)
-- [Command-line arguments](./cli.md)
-- [rustc_driver and rustc_interface](./rustc-driver/intro.md)
-    - [Example: Type checking](./rustc-driver/interacting-with-the-ast.md)
-    - [Example: Getting diagnostics](./rustc-driver/getting-diagnostics.md)
 - [Syntax and the AST](./syntax-intro.md)
     - [Lexing and Parsing](./the-parser.md)
     - [Macro expansion](./macro-expansion.md)
@@ -118,10 +114,22 @@
     - [MIR construction](./mir/construction.md)
     - [MIR visitor and traversal](./mir/visitor.md)
     - [MIR queries and passes: getting the MIR](./mir/passes.md)
-- [Identifiers in the Compiler](./identifiers.md)
-- [Closure expansion](./closure.md)
 - [Inline assembly](./asm.md)
 
+# Supporting Infrastructure
+
+- [Command-line arguments](./cli.md)
+- [rustc_driver and rustc_interface](./rustc-driver/intro.md)
+    - [Example: Type checking](./rustc-driver/interacting-with-the-ast.md)
+    - [Example: Getting diagnostics](./rustc-driver/getting-diagnostics.md)
+- [Errors and Lints](diagnostics.md)
+    - [Diagnostic and subdiagnostic structs](./diagnostics/diagnostic-structs.md)
+    - [Translation](./diagnostics/translation.md)
+    - [`LintStore`](./diagnostics/lintstore.md)
+    - [Error codes](./diagnostics/error-codes.md)
+    - [Diagnostic items](./diagnostics/diagnostic-items.md)
+    - [`ErrorGuaranteed`](./diagnostics/error-guaranteed.md)
+
 # Analysis
 
 - [Prologue](./part-4-intro.md)
@@ -190,13 +198,7 @@
         - [Closure constraints](./borrow_check/region_inference/closure_constraints.md)
         - [Error reporting](./borrow_check/region_inference/error_reporting.md)
     - [Two-phase-borrows](./borrow_check/two_phase_borrows.md)
-- [Errors and Lints](diagnostics.md)
-    - [Diagnostic and subdiagnostic structs](./diagnostics/diagnostic-structs.md)
-    - [Translation](./diagnostics/translation.md)
-    - [`LintStore`](./diagnostics/lintstore.md)
-    - [Error codes](./diagnostics/error-codes.md)
-    - [Diagnostic items](./diagnostics/diagnostic-items.md)
-    - [`ErrorGuaranteed`](./diagnostics/error-guaranteed.md)
+- [Closure capture inference](./closure.md)
 - [Async closures/"coroutine-closures"](coroutine-closures.md)
 
 # MIR to Binaries

src/closure.md

@@ -1,4 +1,4 @@
-# Closure Expansion in rustc
+# Closure Capture Inference
 
 This section describes how rustc handles closures. Closures in Rust are
 effectively "desugared" into structs that contain the values they use (or

src/hir.md

@@ -78,18 +78,40 @@ the compiler a chance to observe that you accessed the data for
 
 ## Identifiers in the HIR
 
-There are a bunch of different identifiers to refer to other nodes or definitions
-in the HIR. In short:
-- A [`DefId`] refers to a *definition* in any crate.
-- A [`LocalDefId`] refers to a *definition* in the currently compiled crate.
-- A [`HirId`] refers to *any node* in the HIR.
+The HIR uses a bunch of different identifiers that coexist and serve different purposes.
 
-For more detailed information, check out the [chapter on identifiers][ids].
+- A [`DefId`], as the name suggests, identifies a particular definition, or top-level
+  item, in a given crate. It is composed of two parts: a [`CrateNum`] which identifies
+  the crate the definition comes from, and a [`DefIndex`] which identifies the definition
+  within the crate. Unlike [`HirId`]s, there isn't a [`DefId`] for every expression, which
+  makes them more stable across compilations.
+
+- A [`LocalDefId`] is basically a [`DefId`] that is known to come from the current crate.
+  This allows us to drop the [`CrateNum`] part, and use the type system to ensure that
+  only local definitions are passed to functions that expect a local definition.
+
+- A [`HirId`] uniquely identifies a node in the HIR of the current crate. It is composed
+  of two parts: an `owner` and a `local_id` that is unique within the `owner`. This
+  combination makes for more stable values which are helpful for incremental compilation.
+  Unlike [`DefId`]s, a [`HirId`] can refer to [fine-grained entities][Node] like expressions,
+  but stays local to the current crate.
+
+- A [`BodyId`] identifies a HIR [`Body`] in the current crate. It is currently only
+  a wrapper around a [`HirId`]. For more info about HIR bodies, please refer to the
+  [HIR chapter][hir-bodies].
+
+These identifiers can be converted into one another through the [HIR map][map].
 
 [`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html
 [`LocalDefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.LocalDefId.html
 [`HirId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir_id/struct.HirId.html
-[ids]: ./identifiers.md#in-the-hir
+[`BodyId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir/struct.BodyId.html
+[`CrateNum`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.CrateNum.html
+[`DefIndex`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefIndex.html
+[`Body`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir/struct.Body.html
+[hir-map]: ./hir.md#the-hir-map
+[hir-bodies]: ./hir.md#hir-bodies
+[map]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/hir/map/struct.Map.html
 
 ## The HIR Map
 

src/identifiers.md

@@ -6,24 +6,39 @@ This happens in two stages: Lexing and Parsing.
 
   1. _Lexing_ takes strings and turns them into streams of [tokens]. For
   example, `foo.bar + buz` would be turned into the tokens `foo`, `.`, `bar`,
-  `+`, and `buz`.
+  `+`, and `buz`. This is implemented in [`rustc_lexer`][lexer].
 
 [tokens]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/token/index.html
 [lexer]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/index.html
 
   2. _Parsing_ takes streams of tokens and turns them into a structured form
   which is easier for the compiler to work with, usually called an [*Abstract
   Syntax Tree* (AST)][ast] . 
-  
-  
-An AST mirrors the structure of a Rust program in memory, using a `Span` to
+
+## The AST
+
+The AST mirrors the structure of a Rust program in memory, using a `Span` to
 link a particular AST node back to its source text. The AST is defined in
 [`rustc_ast`][rustc_ast], along with some definitions for tokens and token
 streams, data structures/traits for mutating ASTs, and shared definitions for
 other AST-related parts of the compiler (like the lexer and
 macro-expansion).
 
-The lexer is developed in [`rustc_lexer`][lexer].
+Every node in the AST has its own [`NodeId`], including top-level items
+such as structs, but also individual statements and expressions. A [`NodeId`]
+is an identifier number that uniquely identifies an AST node within a crate.
+
+However, because they are absolute within a crate, adding or removing a single
+node in the AST causes all the subsequent [`NodeId`]s to change. This renders
+[`NodeId`]s pretty much useless for incremental compilation, where you want as
+few things as possible to change.
+
+[`NodeId`]s are used in all the `rustc` bits that operate directly on the AST,
+like macro expansion and name resolution (more on these over the next couple chapters).
+
+[`NodeId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/node_id/struct.NodeId.html
+
+## Parsing
 
 The parser is defined in [`rustc_parse`][rustc_parse], along with a
 high-level interface to the lexer and some validation routines that run after