incr.comp.: Add some comments.

Author: michaelwoerister

src/librustc/dep_graph/graph.rs

@@ -27,6 +27,14 @@ use super::edges::{DepGraphEdges, DepNodeIndex};
 #[derive(Clone)]
 pub struct DepGraph {
     data: Option<Rc<DepGraphData>>,
+
+    // At the moment we are using DepNode as key here. In the future it might
+    // be possible to use an IndexVec<DepNodeIndex, _> here. At the moment there
+    // are a few problems with that:
+    // - Some fingerprints are needed even if incr. comp. is disabled -- yet
+    //   we need to have a dep-graph to generate DepNodeIndices.
+    // - The architecture is still in flux and it's not clear what how to best
+    //   implement things.
     fingerprints: Rc<RefCell<FxHashMap<DepNode, Fingerprint>>>
 }
 

src/librustc/hir/map/collector.rs

@@ -28,6 +28,8 @@ pub(super) struct NodeCollector<'a, 'hir> {
     /// The parent of this node
     parent_node: NodeId,
 
+    // These fields keep track of the currently relevant DepNodes during
+    // the visitor's traversal.
     current_dep_node_owner: DefIndex,
     current_signature_dep_index: DepNodeIndex,
     current_full_dep_index: DepNodeIndex,
@@ -38,6 +40,8 @@ pub(super) struct NodeCollector<'a, 'hir> {
 
     hcx: StableHashingContext<'a>,
 
+    // We are collecting DepNode::HirBody hashes here so we can compute the
+    // crate hash from then later on.
     hir_body_nodes: Vec<DefPathHash>,
 }
 
@@ -463,11 +467,14 @@ impl<'a, 'hir> Visitor<'hir> for NodeCollector<'a, 'hir> {
     }
 }
 
-
+// We use this with DepGraph::with_task(). Since we are handling only input
+// values here, the "task" computing them just passes them through.
 fn identity_fn<T>(_: &StableHashingContext, item_like: T) -> T {
     item_like
 }
 
+// This is a wrapper structure that allows determining if span values within
+// the wrapped item should be hashed or not.
 struct HirItemLike<T> {
     item_like: T,
     hash_bodies: bool,

src/librustc/ty/context.rs

@@ -1237,6 +1237,10 @@ impl<'a, 'gcx, 'tcx> TyCtxt<'a, 'gcx, 'tcx> {
                                   self.cstore)
     }
 
+    // This method exercises the `in_scope_traits_map` query for all possible
+    // values so that we have their fingerprints available in the DepGraph.
+    // This is only required as long as we still use the old dependency tracking
+    // which needs to have the fingerprints of all input nodes beforehand.
     pub fn precompute_in_scope_traits_hashes(self) {
         for &def_index in self.trait_map.keys() {
             self.in_scope_traits_map(def_index);

src/librustc_data_structures/stable_hasher.rs

@@ -558,10 +558,12 @@ pub fn hash_stable_hashmap<HCX, K, V, R, SK, F, W>(
     entries.hash_stable(hcx, hasher);
 }
 
+
+/// A vector container that makes sure that its items are hashed in a stable
+/// order.
 pub struct StableVec<T>(Vec<T>);
 
 impl<T> StableVec<T> {
-
     pub fn new(v: Vec<T>) -> Self {
         StableVec(v)
     }

src/librustc_driver/test.rs

@@ -133,7 +133,7 @@ fn test_env<F>(source_string: &str,
 
     let arena = DroplessArena::new();
     let arenas = ty::GlobalArenas::new();
-    let hir_map = hir_map::map_crate(&mut hir_forest, &defs);
+    let hir_map = hir_map::map_crate(&sess, &*cstore, &mut hir_forest, &defs);
 
     // run just enough stuff to build a tcx:
     let named_region_map = resolve_lifetime::krate(&sess, &*cstore, &hir_map);