From d33db6ed570a38fa52d8fdf29dbad9a5cdf4c44d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20K=C3=A5re=20Alsaker?= <john.kare.alsaker@gmail.com>
Date: Wed, 8 May 2019 14:27:40 +0200
Subject: [PATCH] Rename HirMap to HirEntryMap and add some comments

---
 src/librustc/hir/map/collector.rs |  6 +++---
 src/librustc/hir/map/mod.rs       | 25 ++++++++++++++++++++-----
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/src/librustc/hir/map/collector.rs b/src/librustc/hir/map/collector.rs
index 24eaeb45ba5..136d683e76b 100644
--- a/src/librustc/hir/map/collector.rs
+++ b/src/librustc/hir/map/collector.rs
@@ -1,7 +1,7 @@
 use super::*;
 use crate::dep_graph::{DepGraph, DepKind, DepNodeIndex};
 use crate::hir;
-use crate::hir::map::HirMap;
+use crate::hir::map::HirEntryMap;
 use crate::hir::def_id::{LOCAL_CRATE, CrateNum};
 use crate::hir::intravisit::{Visitor, NestedVisitorMap};
 use rustc_data_structures::svh::Svh;
@@ -28,7 +28,7 @@ pub(super) struct NodeCollector<'a, 'hir> {
     source_map: &'a SourceMap,
 
     /// The node map
-    map: HirMap<'hir>,
+    map: HirEntryMap<'hir>,
     /// The parent of this node
     parent_node: hir::HirId,
 
@@ -178,7 +178,7 @@ impl<'a, 'hir> NodeCollector<'a, 'hir> {
                                                   crate_disambiguator: CrateDisambiguator,
                                                   cstore: &dyn CrateStore,
                                                   commandline_args_hash: u64)
-                                                  -> (HirMap<'hir>, Svh)
+                                                  -> (HirEntryMap<'hir>, Svh)
     {
         self.hir_body_nodes.sort_unstable_by_key(|bn| bn.0);
 
diff --git a/src/librustc/hir/map/mod.rs b/src/librustc/hir/map/mod.rs
index e6bc4beb450..c2b513a39a8 100644
--- a/src/librustc/hir/map/mod.rs
+++ b/src/librustc/hir/map/mod.rs
@@ -162,7 +162,12 @@ impl Forest {
     }
 }
 
-pub(super) type HirMap<'hir> = [Vec<Option<IndexVec<ItemLocalId, Option<Entry<'hir>>>>>; 2];
+/// This type is effectively a `HashMap<HirId, Entry<'hir>>`,
+/// but is implemented by 3 layers of arrays.
+/// - the outer layer is `[A; 2]` and correspond to the 2 address spaces `DefIndex`es can be in
+/// - then we have `A = Vec<Option<B>>` mapping a `DefIndex`'s index to a inner value
+/// - which is `B = IndexVec<ItemLocalId, Option<Entry<'hir>>` which finally gives you the `Entry`.
+pub(super) type HirEntryMap<'hir> = [Vec<Option<IndexVec<ItemLocalId, Option<Entry<'hir>>>>>; 2];
 
 /// Represents a mapping from `NodeId`s to AST elements and their parent `NodeId`s.
 #[derive(Clone)]
@@ -177,7 +182,7 @@ pub struct Map<'hir> {
     /// The SVH of the local crate.
     pub crate_hash: Svh,
 
-    map: HirMap<'hir>,
+    map: HirEntryMap<'hir>,
 
     definitions: &'hir Definitions,
 
@@ -1011,15 +1016,25 @@ impl<'hir> Map<'hir> {
 
     /// Returns an iterator that yields all the hir ids in the map.
     fn all_ids<'a>(&'a self) -> impl Iterator<Item = HirId> + 'a {
+        // This code is a bit awkward because the map is implemented as 3 levels of arrays,
+        // see the comment on `HirEntryMap`.
         let map = &self.map;
+
+        // Look at both the def index address spaces
         let spaces = [DefIndexAddressSpace::Low, DefIndexAddressSpace::High].iter().cloned();
         spaces.flat_map(move |space| {
-            map[space.index()].iter().enumerate().filter_map(|(i, local_map)| {
+            // Iterate over all the indices in the address space and return a reference to
+            // local maps and their index given that they exist.
+            let local_maps = map[space.index()].iter().enumerate().filter_map(|(i, local_map)| {
                 local_map.as_ref().map(|m| (i, m))
-            }).flat_map(move |(def_index, local_map)| {
+            });
+
+            local_maps.flat_map(move |(array_index, local_map)| {
+                // Iterate over each valid entry in the local map
                 local_map.iter_enumerated().filter_map(move |(i, entry)| entry.map(move |_| {
+                    // Reconstruct the HirId based on the 3 indices we used to find it
                     HirId {
-                        owner: DefIndex::from_array_index(def_index, space),
+                        owner: DefIndex::from_array_index(array_index, space),
                         local_id: i,
                     }
                 }))