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>

Author: 3 people

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