Add a section on identifiers in the MIR (#951)

* Add a section on identifiers in the MIR

* Better wording

* Use loose lists; fix typo; fix link

* Update info

* Note how you can retrieve the associated data

Suggested by @LeSeulArtichaut.

* Update src/identifiers.md

Co-authored-by: Léo Lanteri Thauvin <leseulartichaut@gmail.com>

* Add TODO for `Promoted` re `GlobalId`

Co-authored-by: Oli Scherer <github35764891676564198441@oli-obk.de>
Co-authored-by: Léo Lanteri Thauvin <leseulartichaut@gmail.com>

1 files changed, 47 insertions, 2 deletions

diff --git a/src/doc/rustc-dev-guide/src/identifiers.md b/src/doc/rustc-dev-guide/src/identifiers.md
index f485132c640..3923c9332eb 100644
--- a/src/doc/rustc-dev-guide/src/identifiers.md
+++ b/src/doc/rustc-dev-guide/src/identifiers.md
@@ -12,7 +12,7 @@ A [`NodeId`] is an identifier number that uniquely identifies an AST node within
 a crate. Every node in the AST has its own [`NodeId`], including top-level items
 such as structs, but also individual statements and expressions.
 
-However, because they are absolute within in a crate, adding or removing a single
+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.
@@ -31,14 +31,17 @@ The HIR uses a bunch of different identifiers that coexist and serve different p
   the crate the definition comes from, and a [`DefIndex`] which identifies the definition
   within the crate. Unlike [`NodeId`]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 currenty only
   a wrapper around a [`HirId`]. For more info about HIR bodies, please refer to the
   [HIR chapter][hir-bodies].
@@ -60,4 +63,46 @@ See the [HIR chapter][hir-map] for more detailed information.
 
 ## In the MIR
 
-**TODO**
+- [`BasicBlock`] identifies a *basic block*. It points to an instance of
+  [`BasicBlockData`], which can be retrieved by indexing into
+  [`Body::basic_blocks()`] (note that you must call a function; the field is
+  private).
+
+- [`Local`] identifies a local variable in a function. Its associated data is in
+  [`LocalDecl`], which can be retrieved by indexing into [`Body.local_decls`].
+
+- [`Field`] identifies a struct's, union's, or enum variant's field. It is used
+  as a "projection" in [`Place`].
+
+- [`SourceScope`] identifies a name scope in the original source code. Used for
+  diagnostics and for debuginfo in debuggers. It points to an instance of
+  [`SourceScopeData`], which can be retrieved by indexing into
+  [`Body.source_scopes`].
+
+- [`Promoted`] identifies a promoted constant within another item (related to
+  const evaluation). Note: it is unique only locally within the item, so it
+  should be associated with a `DefId`.
+  [`GlobalId`] will give you a more specific identifier (TODO).
+
+- [`GlobalId`] identifies a global variable: a `const`, a `static`, a `const fn`
+  where all arguments are [zero-sized types], or a promoted constant.
+
+- [`Location`] represents the location in the MIR of a statement or terminator.
+  It identifies the block (using [`BasicBlock`]) and the index of the statement
+  or terminator in the block.
+
+[`BasicBlock`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.BasicBlock.html
+[`BasicBlockData`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.BasicBlockData.html
+[`Body::basic_blocks()`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#method.basic_blocks
+[`Local`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Local.html
+[`LocalDecl`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.LocalDecl.html
+[`Body.local_decls`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#structfield.local_decls
+[`Field`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Field.html
+[`Place`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Place.html
+[`SourceScope`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.SourceScope.html
+[`SourceScopeData`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.SourceScopeData.html
+[`Body.source_scopes`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#structfield.source_scopes
+[`Promoted`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Promoted.html
+[`GlobalId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/struct.GlobalId.html
+[`Location`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Location.html
+[zero-sized types]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts