add docs

src/librustc_mir/borrow_check/nll/liveness_map.rs

@@ -8,25 +8,41 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! For the NLL computation, we need to compute liveness, but only for those
+//! local variables whose types contain regions. The others are not of interest
+//! to us. This file defines a new index type (LocalWithRegion) that indexes into
+//! a list of "variables whose type contain regions". It also defines a map from
+//! Local to LocalWithRegion and vice versa -- this map can be given to the
+//! liveness code so that it only operates over variables with regions in their
+//! types, instead of all variables.
+
+use rustc::ty::TypeFoldable;
 use rustc_data_structures::indexed_vec::IndexVec;
 use rustc::mir::{Mir, Local};
 use util::liveness::LiveVariableMap;
-use rustc_data_structures::indexed_vec::Idx;
-use rustc::ty::TypeFoldable;
 
+use rustc_data_structures::indexed_vec::Idx;
+
+/// Map between Local and LocalWithRegion indices: this map is supplied to the
+/// liveness code so that it will only analyze those variables whose types
+/// contain regions.
 crate struct NllLivenessMap {
+    /// For each local variable, contains either None (if the type has no regions)
+    /// or Some(i) with a suitable index.
     pub from_local: IndexVec<Local, Option<LocalWithRegion>>,
+    /// For each LocalWithRegion, maps back to the original Local index.
     pub to_local: IndexVec<LocalWithRegion, Local>,
 
 }
 
 impl LiveVariableMap for NllLivenessMap {
-    type LiveVar = LocalWithRegion;
 
     fn from_local(&self, local: Local) -> Option<Self::LiveVar> {
         self.from_local[local]
     }
 
+    type LiveVar = LocalWithRegion;
+
     fn from_live_var(&self, local: Self::LiveVar) -> Local {
         self.to_local[local]
     }
@@ -37,6 +53,8 @@ impl LiveVariableMap for NllLivenessMap {
 }
 
 impl NllLivenessMap {
+    /// Iterates over the variables in Mir and assigns each Local whose type contains
+    /// regions a LocalWithRegion index. Returns a map for converting back and forth.
     pub fn compute(mir: &Mir) -> Self {
         let mut to_local = IndexVec::default();
         let from_local: IndexVec<Local,Option<_>> = mir
@@ -55,4 +73,5 @@ impl NllLivenessMap {
     }
 }
 
+/// Index given to each local variable whose type contains a region.
 newtype_index!(LocalWithRegion);