From fd79ed42254d7483569ccc48ef35a79635ed5881 Mon Sep 17 00:00:00 2001
From: Camelid <camelidcamel@gmail.com>
Date: Mon, 14 Sep 2020 20:05:00 -0700
Subject: [PATCH] Add docs for `BasicBlock`

---
 compiler/rustc_middle/src/mir/mod.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/compiler/rustc_middle/src/mir/mod.rs b/compiler/rustc_middle/src/mir/mod.rs
index d32a7a4062e..aeaea0d102c 100644
--- a/compiler/rustc_middle/src/mir/mod.rs
+++ b/compiler/rustc_middle/src/mir/mod.rs
@@ -1076,6 +1076,19 @@ pub struct VarDebugInfo<'tcx> {
 // BasicBlock
 
 rustc_index::newtype_index! {
+    /// The unit of the MIR [control-flow graph][CFG].
+    ///
+    /// There is no branching (e.g., `if`s, function calls, etc.) within a basic block, which makes
+    /// it easier to do [data-flow analyses] and optimizations. Basic blocks consist of a series of
+    /// [statements][`Statement`], ending with a [terminator][`Terminator`]. Basic blocks can have
+    /// multiple predecessors and successors.
+    ///
+    /// Read more about basic blocks in the [rustc-dev-guide][guide-mir].
+    ///
+    /// [CFG]: https://rustc-dev-guide.rust-lang.org/appendix/background.html#cfg
+    /// [data-flow analyses]:
+    ///     https://rustc-dev-guide.rust-lang.org/appendix/background.html#what-is-a-dataflow-analysis
+    /// [guide-mir]: https://rustc-dev-guide.rust-lang.org/mir/
     pub struct BasicBlock {
         derive [HashStable]
         DEBUG_FORMAT = "bb{}",
@@ -1092,6 +1105,7 @@ impl BasicBlock {
 ///////////////////////////////////////////////////////////////////////////
 // BasicBlockData and Terminator
 
+/// See [`BasicBlock`] for documentation on what basic blocks are at a high level.
 #[derive(Clone, Debug, TyEncodable, TyDecodable, HashStable, TypeFoldable)]
 pub struct BasicBlockData<'tcx> {
     /// List of statements in this block.