address comments from mw

Author: nikomatsakis

src/librustc_incremental/persist/load.rs

@@ -113,10 +113,28 @@ pub fn decode_dep_graph<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>,
     // TODO -- this could be more efficient if we integrated the `DefIdDirectory` and
     // pred set more deeply
 
-    // Compute the set of Hir nodes whose data has changed or which have been removed.
+    // Compute the set of Hir nodes whose data has changed or which
+    // have been removed.  These are "raw" source nodes, which means
+    // that they still use the original `DefPathIndex` values from the
+    // encoding, rather than having been retraced to a `DefId`. The
+    // reason for this is that this way we can include nodes that have
+    // been removed (which no longer have a `DefId` in the current
+    // compilation).
     let dirty_raw_source_nodes = dirty_nodes(tcx, &serialized_dep_graph.hashes, &retraced);
 
-    // Create a (maybe smaller) list of
+    // Create a list of (raw-source-node ->
+    // retracted-target-node) edges. In the process of retracing the
+    // target nodes, we may discover some of them def-paths no longer exist,
+    // in which case there is no need to mark the corresopnding nodes as dirty
+    // (they are just not present). So this list may be smaller than the original.
+    //
+    // Note though that in the common case the target nodes are
+    // `DepNode::WorkProduct` instances, and those don't have a
+    // def-id, so they will never be considered to not exist. Instead,
+    // we do a secondary hashing step (later, in trans) when we know
+    // the set of symbols that go into a work-product: if any symbols
+    // have been removed (or added) the hash will be different and
+    // we'll ignore the work-product then.
     let retraced_edges: Vec<_> =
         serialized_dep_graph.edges.iter()
                                   .filter_map(|&(ref raw_source_node, ref raw_target_node)| {
@@ -125,7 +143,8 @@ pub fn decode_dep_graph<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>,
                                   })
                                   .collect();
 
-    // Compute which work-products have changed.
+    // Compute which work-products have an input that has changed or
+    // been removed. Put the dirty ones into a set.
     let mut dirty_target_nodes = FnvHashSet();
     for &(raw_source_node, ref target_node) in &retraced_edges {
         if dirty_raw_source_nodes.contains(raw_source_node) {

src/librustc_incremental/persist/save.rs

@@ -110,7 +110,12 @@ pub fn encode_dep_graph(preds: &Predecessors,
     let mut edges = vec![];
     for (&target, sources) in &preds.inputs {
         match *target {
-            DepNode::MetaData(_) => continue, // see encode_metadata_hashes instead
+            DepNode::MetaData(ref def_id) => {
+                // Metadata *targets* are always local metadata nodes. We handle
+                // those in `encode_metadata_hashes`, which comes later.
+                assert!(def_id.is_local());
+                continue;
+            }
             _ => (),
         }
         let target = builder.map(target);
@@ -186,7 +191,7 @@ pub fn encode_metadata_hashes(tcx: TyCtxt,
         // Create a vector containing a pair of (source-id, hash).
         // The source-id is stored as a `DepNode<u64>`, where the u64
         // is the det. hash of the def-path. This is convenient
-        // because we can sort this to get a table ordering across
+        // because we can sort this to get a stable ordering across
         // compilations, even if the def-ids themselves have changed.
         let mut hashes: Vec<(DepNode<u64>, u64)> = sources.iter()
             .map(|dep_node| {