From 7b4dca282a0bfad265238d04b22f7bdb0d498d74 Mon Sep 17 00:00:00 2001
From: Dylan MacKenzie <ecstaticmorse@gmail.com>
Date: Sun, 19 Jan 2020 18:47:29 -0800
Subject: [PATCH] Document all methods

---
 src/librustc_mir/dataflow/generic/engine.rs |  6 ++++++
 src/librustc_mir/dataflow/generic/mod.rs    | 10 +++++++---
 src/librustc_mir/dataflow/generic/tests.rs  |  3 ++-
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/librustc_mir/dataflow/generic/engine.rs b/src/librustc_mir/dataflow/generic/engine.rs
index 3322177006666..c0152b0c7d504 100644
--- a/src/librustc_mir/dataflow/generic/engine.rs
+++ b/src/librustc_mir/dataflow/generic/engine.rs
@@ -121,11 +121,17 @@ where
         }
     }
 
+    /// Signals that we do not want dataflow state to propagate across unwind edges for these
+    /// `BasicBlock`s.
+    ///
+    /// You must take care that `dead_unwinds` does not contain a `BasicBlock` that *can* actually
+    /// unwind during execution. Otherwise, your dataflow results will not be correct.
     pub fn dead_unwinds(mut self, dead_unwinds: &'a BitSet<BasicBlock>) -> Self {
         self.dead_unwinds = Some(dead_unwinds);
         self
     }
 
+    /// Computes the fixpoint for this dataflow problem and returns it.
     pub fn iterate_to_fixpoint(mut self) -> Results<'tcx, A> {
         let mut temp_state = BitSet::new_empty(self.bits_per_block);
 
diff --git a/src/librustc_mir/dataflow/generic/mod.rs b/src/librustc_mir/dataflow/generic/mod.rs
index 897b95ea99602..c9b4f875ebdf8 100644
--- a/src/librustc_mir/dataflow/generic/mod.rs
+++ b/src/librustc_mir/dataflow/generic/mod.rs
@@ -60,11 +60,13 @@ impl<A> Results<'tcx, A>
 where
     A: Analysis<'tcx>,
 {
-    pub fn into_cursor(self, body: &'mir mir::Body<'tcx>) -> ResultsCursor<'mir, 'tcx, A> {
+    /// Creates a `ResultsCursor` that can inspect these `Results`.
+    pub fn into_results_cursor(self, body: &'mir mir::Body<'tcx>) -> ResultsCursor<'mir, 'tcx, A> {
         ResultsCursor::new(body, self)
     }
 
-    pub fn on_block_entry(&self, block: BasicBlock) -> &BitSet<A::Idx> {
+    /// Gets the entry set for the given block.
+    pub fn entry_set_for_block(&self, block: BasicBlock) -> &BitSet<A::Idx> {
         &self.entry_sets[block]
     }
 }
@@ -288,12 +290,14 @@ pub trait GenKill<T> {
     /// Removes `elem` from the state vector.
     fn kill(&mut self, elem: T);
 
+    /// Calls `gen` for each element in `elems`.
     fn gen_all(&mut self, elems: impl IntoIterator<Item = T>) {
         for elem in elems {
             self.gen(elem);
         }
     }
 
+    /// Calls `kill` for each element in `elems`.
     fn kill_all(&mut self, elems: impl IntoIterator<Item = T>) {
         for elem in elems {
             self.kill(elem);
@@ -304,7 +308,7 @@ pub trait GenKill<T> {
 /// Stores a transfer function for a gen/kill problem.
 ///
 /// Calling `gen`/`kill` on a `GenKillSet` will "build up" a transfer function so that it can be
-/// applied to a state vector efficiently. When there are multiple calls to `gen` and/or `kill` for
+/// applied multiple times efficiently. When there are multiple calls to `gen` and/or `kill` for
 /// the same element, the most recent one takes precedence.
 #[derive(Clone)]
 pub struct GenKillSet<T: Idx> {
diff --git a/src/librustc_mir/dataflow/generic/tests.rs b/src/librustc_mir/dataflow/generic/tests.rs
index cc339cf8ce955..50d4bdb67f755 100644
--- a/src/librustc_mir/dataflow/generic/tests.rs
+++ b/src/librustc_mir/dataflow/generic/tests.rs
@@ -276,7 +276,8 @@ fn cursor_seek() {
     let body = &body;
     let analysis = MockAnalysis { body };
 
-    let mut cursor = Results { entry_sets: analysis.mock_entry_sets(), analysis }.into_cursor(body);
+    let mut cursor =
+        Results { entry_sets: analysis.mock_entry_sets(), analysis }.into_results_cursor(body);
 
     // Sanity check: the mock call return effect is unique and actually being applied.
     let call_terminator_loc = Location { block: BasicBlock::from_usize(2), statement_index: 2 };