rustc: doc comments

12 files changed, 61 insertions, 61 deletions

diff --git a/src/librustc_data_structures/base_n.rs b/src/librustc_data_structures/base_n.rs
index c9c1933f25b..f1bd3f03aef 100644
--- a/src/librustc_data_structures/base_n.rs
+++ b/src/librustc_data_structures/base_n.rs
@@ -1,4 +1,4 @@
-/// Convert unsigned integers into a string representation with some base.
+/// Converts unsigned integers into a string representation with some base.
 /// Bases up to and including 36 can be used for case-insensitive things.
 
 use std::str;
diff --git a/src/librustc_data_structures/bit_set.rs b/src/librustc_data_structures/bit_set.rs
index 05d2185ae69..ff7964646d6 100644
--- a/src/librustc_data_structures/bit_set.rs
+++ b/src/librustc_data_structures/bit_set.rs
@@ -27,7 +27,7 @@ pub struct BitSet<T: Idx> {
 }
 
 impl<T: Idx> BitSet<T> {
-    /// Create a new, empty bitset with a given `domain_size`.
+    /// Creates a new, empty bitset with a given `domain_size`.
     #[inline]
     pub fn new_empty(domain_size: usize) -> BitSet<T> {
         let num_words = num_words(domain_size);
@@ -38,7 +38,7 @@ impl<T: Idx> BitSet<T> {
         }
     }
 
-    /// Create a new, filled bitset with a given `domain_size`.
+    /// Creates a new, filled bitset with a given `domain_size`.
     #[inline]
     pub fn new_filled(domain_size: usize) -> BitSet<T> {
         let num_words = num_words(domain_size);
@@ -51,7 +51,7 @@ impl<T: Idx> BitSet<T> {
         result
     }
 
-    /// Get the domain size.
+    /// Gets the domain size.
     pub fn domain_size(&self) -> usize {
         self.domain_size
     }
@@ -85,7 +85,7 @@ impl<T: Idx> BitSet<T> {
         self.words.iter().map(|e| e.count_ones() as usize).sum()
     }
 
-    /// True if `self` contains `elem`.
+    /// Returns `true` if `self` contains `elem`.
     #[inline]
     pub fn contains(&self, elem: T) -> bool {
         assert!(elem.index() < self.domain_size);
@@ -106,7 +106,7 @@ impl<T: Idx> BitSet<T> {
         self.words.iter().all(|a| *a == 0)
     }
 
-    /// Insert `elem`. Returns true if the set has changed.
+    /// Insert `elem`. Returns whether the set has changed.
     #[inline]
     pub fn insert(&mut self, elem: T) -> bool {
         assert!(elem.index() < self.domain_size);
@@ -126,7 +126,7 @@ impl<T: Idx> BitSet<T> {
         self.clear_excess_bits();
     }
 
-    /// Returns true if the set has changed.
+    /// Returns `true` if the set has changed.
     #[inline]
     pub fn remove(&mut self, elem: T) -> bool {
         assert!(elem.index() < self.domain_size);
@@ -138,26 +138,26 @@ impl<T: Idx> BitSet<T> {
         new_word != word
     }
 
-    /// Set `self = self | other` and return true if `self` changed
+    /// Sets `self = self | other` and returns `true` if `self` changed
     /// (i.e., if new bits were added).
     pub fn union(&mut self, other: &impl UnionIntoBitSet<T>) -> bool {
         other.union_into(self)
     }
 
-    /// Set `self = self - other` and return true if `self` changed.
+    /// Sets `self = self - other` and returns `true` if `self` changed.
     /// (i.e., if any bits were removed).
     pub fn subtract(&mut self, other: &impl SubtractFromBitSet<T>) -> bool {
         other.subtract_from(self)
     }
 
-    /// Set `self = self & other` and return true if `self` changed.
+    /// Sets `self = self & other` and return `true` if `self` changed.
     /// (i.e., if any bits were removed).
     pub fn intersect(&mut self, other: &BitSet<T>) -> bool {
         assert_eq!(self.domain_size, other.domain_size);
         bitwise(&mut self.words, &other.words, |a, b| { a & b })
     }
 
-    /// Get a slice of the underlying words.
+    /// Gets a slice of the underlying words.
     pub fn words(&self) -> &[Word] {
         &self.words
     }
@@ -611,7 +611,7 @@ impl<T: Idx> GrowableBitSet<T> {
         GrowableBitSet { bit_set: BitSet::new_empty(bits) }
     }
 
-    /// Returns true if the set has changed.
+    /// Returns `true` if the set has changed.
     #[inline]
     pub fn insert(&mut self, elem: T) -> bool {
         self.ensure(elem.index() + 1);
@@ -645,7 +645,7 @@ pub struct BitMatrix<R: Idx, C: Idx> {
 }
 
 impl<R: Idx, C: Idx> BitMatrix<R, C> {
-    /// Create a new `rows x columns` matrix, initially empty.
+    /// Creates a new `rows x columns` matrix, initially empty.
     pub fn new(num_rows: usize, num_columns: usize) -> BitMatrix<R, C> {
         // For every element, we need one bit for every other
         // element. Round up to an even number of words.
@@ -668,7 +668,7 @@ impl<R: Idx, C: Idx> BitMatrix<R, C> {
     /// Sets the cell at `(row, column)` to true. Put another way, insert
     /// `column` to the bitset for `row`.
     ///
-    /// Returns true if this changed the matrix, and false otherwise.
+    /// Returns `true` if this changed the matrix.
     pub fn insert(&mut self, row: R, column: C) -> bool {
         assert!(row.index() < self.num_rows && column.index() < self.num_columns);
         let (start, _) = self.range(row);
@@ -691,7 +691,7 @@ impl<R: Idx, C: Idx> BitMatrix<R, C> {
         (self.words[start + word_index] & mask) != 0
     }
 
-    /// Returns those indices that are true in rows `a` and `b`.  This
+    /// Returns those indices that are true in rows `a` and `b`. This
     /// is an O(n) operation where `n` is the number of elements
     /// (somewhat independent from the actual size of the
     /// intersection, in particular).
@@ -715,8 +715,8 @@ impl<R: Idx, C: Idx> BitMatrix<R, C> {
         result
     }
 
-    /// Add the bits from row `read` to the bits from row `write`,
-    /// return true if anything changed.
+    /// Adds the bits from row `read` to the bits from row `write`, and
+    /// returns `true` if anything changed.
     ///
     /// This is used when computing transitive reachability because if
     /// you have an edge `write -> read`, because in that case
@@ -772,7 +772,7 @@ where
 }
 
 impl<R: Idx, C: Idx> SparseBitMatrix<R, C> {
-    /// Create a new empty sparse bit matrix with no rows or columns.
+    /// Creates a new empty sparse bit matrix with no rows or columns.
     pub fn new(num_columns: usize) -> Self {
         Self {
             num_columns,
@@ -793,7 +793,7 @@ impl<R: Idx, C: Idx> SparseBitMatrix<R, C> {
     /// Sets the cell at `(row, column)` to true. Put another way, insert
     /// `column` to the bitset for `row`.
     ///
-    /// Returns true if this changed the matrix, and false otherwise.
+    /// Returns `true` if this changed the matrix.
     pub fn insert(&mut self, row: R, column: C) -> bool {
         self.ensure_row(row).insert(column)
     }
@@ -806,8 +806,8 @@ impl<R: Idx, C: Idx> SparseBitMatrix<R, C> {
         self.row(row).map_or(false, |r| r.contains(column))
     }
 
-    /// Add the bits from row `read` to the bits from row `write`,
-    /// return true if anything changed.
+    /// Adds the bits from row `read` to the bits from row `write`, and
+    /// returns `true` if anything changed.
     ///
     /// This is used when computing transitive reachability because if
     /// you have an edge `write -> read`, because in that case
diff --git a/src/librustc_data_structures/graph/implementation/mod.rs b/src/librustc_data_structures/graph/implementation/mod.rs
index a8b73409406..de4b1bcd0c2 100644
--- a/src/librustc_data_structures/graph/implementation/mod.rs
+++ b/src/librustc_data_structures/graph/implementation/mod.rs
@@ -14,7 +14,7 @@
 //! stored. The edges are stored in a central array, but they are also
 //! threaded onto two linked lists for each node, one for incoming edges
 //! and one for outgoing edges. Note that every edge is a member of some
-//! incoming list and some outgoing list.  Basically you can load the
+//! incoming list and some outgoing list. Basically you can load the
 //! first index of the linked list from the node data structures (the
 //! field `first_edge`) and then, for each edge, load the next index from
 //! the field `next_edge`). Each of those fields is an array that should
@@ -79,7 +79,7 @@ pub const OUTGOING: Direction = Direction { repr: 0 };
 pub const INCOMING: Direction = Direction { repr: 1 };
 
 impl NodeIndex {
-    /// Returns unique id (unique with respect to the graph holding associated node).
+    /// Returns unique ID (unique with respect to the graph holding associated node).
     pub fn node_id(self) -> usize {
         self.0
     }
diff --git a/src/librustc_data_structures/graph/scc/mod.rs b/src/librustc_data_structures/graph/scc/mod.rs
index e3264fda262..24c5448639e 100644
--- a/src/librustc_data_structures/graph/scc/mod.rs
+++ b/src/librustc_data_structures/graph/scc/mod.rs
@@ -200,7 +200,7 @@ where
         }
     }
 
-    /// Visit a node during the DFS. We first examine its current
+    /// Visits a node during the DFS. We first examine its current
     /// state -- if it is not yet visited (`NotVisited`), we can push
     /// it onto the stack and start walking its successors.
     ///
diff --git a/src/librustc_data_structures/indexed_vec.rs b/src/librustc_data_structures/indexed_vec.rs
index 516ea7fb7d9..09aec50e4bb 100644
--- a/src/librustc_data_structures/indexed_vec.rs
+++ b/src/librustc_data_structures/indexed_vec.rs
@@ -12,7 +12,7 @@ use rustc_serialize as serialize;
 
 /// Represents some newtyped `usize` wrapper.
 ///
-/// (purpose: avoid mixing indexes for different bitvector domains.)
+/// Purpose: avoid mixing indexes for different bitvector domains.
 pub trait Idx: Copy + 'static + Ord + Debug + Hash {
     fn new(idx: usize) -> Self;
 
@@ -144,19 +144,19 @@ macro_rules! newtype_index {
                 unsafe { $type { private: value } }
             }
 
-            /// Extract value of this index as an integer.
+            /// Extracts the value of this index as an integer.
             #[inline]
             $v fn index(self) -> usize {
                 self.as_usize()
             }
 
-            /// Extract value of this index as a usize.
+            /// Extracts the value of this index as a `u32`.
             #[inline]
             $v fn as_u32(self) -> u32 {
                 self.private
             }
 
-            /// Extract value of this index as a u32.
+            /// Extracts the value of this index as a `usize`.
             #[inline]
             $v fn as_usize(self) -> usize {
                 self.as_u32() as usize
@@ -641,7 +641,7 @@ impl<I: Idx, T> IndexVec<I, T> {
         self.raw.get_mut(index.index())
     }
 
-    /// Return mutable references to two distinct elements, a and b. Panics if a == b.
+    /// Returns mutable references to two distinct elements, a and b. Panics if a == b.
     #[inline]
     pub fn pick2_mut(&mut self, a: I, b: I) -> (&mut T, &mut T) {
         let (ai, bi) = (a.index(), b.index());
diff --git a/src/librustc_data_structures/obligation_forest/graphviz.rs b/src/librustc_data_structures/obligation_forest/graphviz.rs
index 72551b42324..a0363e165e0 100644
--- a/src/librustc_data_structures/obligation_forest/graphviz.rs
+++ b/src/librustc_data_structures/obligation_forest/graphviz.rs
@@ -7,8 +7,8 @@ use std::sync::atomic::AtomicUsize;
 use std::sync::atomic::Ordering;
 
 impl<O: ForestObligation> ObligationForest<O> {
-    /// Create a graphviz representation of the obligation forest.  Given a directory this will
-    /// create files with name of the format `<counter>_<description>.gv`.  The counter is
+    /// Creates a graphviz representation of the obligation forest. Given a directory this will
+    /// create files with name of the format `<counter>_<description>.gv`. The counter is
     /// global and is maintained internally.
     ///
     /// Calling this will do nothing unless the environment variable
diff --git a/src/librustc_data_structures/obligation_forest/mod.rs b/src/librustc_data_structures/obligation_forest/mod.rs
index 546bb64168e..4490e5f86d2 100644
--- a/src/librustc_data_structures/obligation_forest/mod.rs
+++ b/src/librustc_data_structures/obligation_forest/mod.rs
@@ -64,7 +64,7 @@
 //! #### Snapshots
 //!
 //! The `ObligationForest` supports a limited form of snapshots; see
-//! `start_snapshot`; `commit_snapshot`; and `rollback_snapshot`. In
+//! `start_snapshot`, `commit_snapshot`, and `rollback_snapshot`. In
 //! particular, you can use a snapshot to roll back new root
 //! obligations. However, it is an error to attempt to
 //! `process_obligations` during a snapshot.
@@ -72,7 +72,7 @@
 //! ### Implementation details
 //!
 //! For the most part, comments specific to the implementation are in the
-//! code.  This file only contains a very high-level overview. Basically,
+//! code. This file only contains a very high-level overview. Basically,
 //! the forest is stored in a vector. Each element of the vector is a node
 //! in some tree. Each node in the vector has the index of an (optional)
 //! parent and (for convenience) its root (which may be itself). It also
@@ -163,7 +163,7 @@ pub struct ObligationForest<O: ForestObligation> {
 
     obligation_tree_id_generator: ObligationTreeIdGenerator,
 
-    /// Per tree error cache.  This is used to deduplicate errors,
+    /// Per tree error cache. This is used to deduplicate errors,
     /// which is necessary to avoid trait resolution overflow in
     /// some cases.
     ///
@@ -268,13 +268,13 @@ impl<O: ForestObligation> ObligationForest<O> {
         }
     }
 
-    /// Return the total number of nodes in the forest that have not
+    /// Returns the total number of nodes in the forest that have not
     /// yet been fully resolved.
     pub fn len(&self) -> usize {
         self.nodes.len()
     }
 
-    /// Registers an obligation
+    /// Registers an obligation.
     ///
     /// This CAN be done in a snapshot
     pub fn register_obligation(&mut self, obligation: O) {
@@ -341,7 +341,7 @@ impl<O: ForestObligation> ObligationForest<O> {
         }
     }
 
-    /// Convert all remaining obligations to the given error.
+    /// Converts all remaining obligations to the given error.
     ///
     /// This cannot be done during a snapshot.
     pub fn to_errors<E: Clone>(&mut self, error: E) -> Vec<Error<O, E>> {
@@ -380,10 +380,10 @@ impl<O: ForestObligation> ObligationForest<O> {
             .insert(node.obligation.as_predicate().clone());
     }
 
-    /// Perform a pass through the obligation list. This must
+    /// Performs a pass through the obligation list. This must
     /// be called in a loop until `outcome.stalled` is false.
     ///
-    /// This CANNOT be unrolled (presently, at least).
+    /// This _cannot_ be unrolled (presently, at least).
     pub fn process_obligations<P>(&mut self, processor: &mut P, do_completed: DoCompleted)
                                   -> Outcome<O, P::Error>
         where P: ObligationProcessor<Obligation=O>
@@ -461,7 +461,7 @@ impl<O: ForestObligation> ObligationForest<O> {
         }
     }
 
-    /// Mark all NodeState::Success nodes as NodeState::Done and
+    /// Mark all `NodeState::Success` nodes as `NodeState::Done` and
     /// report all cycles between them. This should be called
     /// after `mark_as_waiting` marks all nodes with pending
     /// subobligations as NodeState::Waiting.
@@ -566,7 +566,7 @@ impl<O: ForestObligation> ObligationForest<O> {
         }
     }
 
-    /// Marks all nodes that depend on a pending node as NodeState::Waiting.
+    /// Marks all nodes that depend on a pending node as `NodeState::Waiting`.
     fn mark_as_waiting(&self) {
         for node in &self.nodes {
             if node.state.get() == NodeState::Waiting {
diff --git a/src/librustc_data_structures/owning_ref/mod.rs b/src/librustc_data_structures/owning_ref/mod.rs
index 30e510cc5b0..236559dcd7c 100644
--- a/src/librustc_data_structures/owning_ref/mod.rs
+++ b/src/librustc_data_structures/owning_ref/mod.rs
@@ -286,7 +286,7 @@ impl<T> Erased for T {}
 pub unsafe trait IntoErased<'a> {
     /// Owner with the dereference type substituted to `Erased`.
     type Erased;
-    /// Perform the type erasure.
+    /// Performs the type erasure.
     fn into_erased(self) -> Self::Erased;
 }
 
@@ -296,7 +296,7 @@ pub unsafe trait IntoErased<'a> {
 pub unsafe trait IntoErasedSend<'a> {
     /// Owner with the dereference type substituted to `Erased + Send`.
     type Erased: Send;
-    /// Perform the type erasure.
+    /// Performs the type erasure.
     fn into_erased_send(self) -> Self::Erased;
 }
 
@@ -306,7 +306,7 @@ pub unsafe trait IntoErasedSend<'a> {
 pub unsafe trait IntoErasedSendSync<'a> {
     /// Owner with the dereference type substituted to `Erased + Send + Sync`.
     type Erased: Send + Sync;
-    /// Perform the type erasure.
+    /// Performs the type erasure.
     fn into_erased_send_sync(self) -> Self::Erased;
 }
 
@@ -844,7 +844,7 @@ pub trait ToHandleMut {
 impl<O, H> OwningHandle<O, H>
     where O: StableAddress, O::Target: ToHandle<Handle = H>, H: Deref,
 {
-    /// Create a new `OwningHandle` for a type that implements `ToHandle`. For types
+    /// Creates a new `OwningHandle` for a type that implements `ToHandle`. For types
     /// that don't implement `ToHandle`, callers may invoke `new_with_fn`, which accepts
     /// a callback to perform the conversion.
     pub fn new(o: O) -> Self {
@@ -855,7 +855,7 @@ impl<O, H> OwningHandle<O, H>
 impl<O, H> OwningHandle<O, H>
     where O: StableAddress, O::Target: ToHandleMut<HandleMut = H>, H: DerefMut,
 {
-    /// Create a new mutable `OwningHandle` for a type that implements `ToHandleMut`.
+    /// Creates a new mutable `OwningHandle` for a type that implements `ToHandleMut`.
     pub fn new_mut(o: O) -> Self {
         OwningHandle::new_with_fn(o, |x| unsafe { O::Target::to_handle_mut(x) })
     }
@@ -864,7 +864,7 @@ impl<O, H> OwningHandle<O, H>
 impl<O, H> OwningHandle<O, H>
     where O: StableAddress, H: Deref,
 {
-    /// Create a new OwningHandle. The provided callback will be invoked with
+    /// Creates a new OwningHandle. The provided callback will be invoked with
     /// a pointer to the object owned by `o`, and the returned value is stored
     /// as the object to which this `OwningHandle` will forward `Deref` and
     /// `DerefMut`.
@@ -882,7 +882,7 @@ impl<O, H> OwningHandle<O, H>
         }
     }
 
-    /// Create a new OwningHandle. The provided callback will be invoked with
+    /// Creates a new OwningHandle. The provided callback will be invoked with
     /// a pointer to the object owned by `o`, and the returned value is stored
     /// as the object to which this `OwningHandle` will forward `Deref` and
     /// `DerefMut`.
diff --git a/src/librustc_data_structures/sip128.rs b/src/librustc_data_structures/sip128.rs
index 9ec9a398400..06f157f9729 100644
--- a/src/librustc_data_structures/sip128.rs
+++ b/src/librustc_data_structures/sip128.rs
@@ -44,7 +44,7 @@ macro_rules! compress {
     });
 }
 
-/// Load an integer of the desired type from a byte stream, in LE order. Uses
+/// Loads an integer of the desired type from a byte stream, in LE order. Uses
 /// `copy_nonoverlapping` to let the compiler generate the most efficient way
 /// to load it from a possibly unaligned address.
 ///
@@ -61,7 +61,7 @@ macro_rules! load_int_le {
     });
 }
 
-/// Load an u64 using up to 7 bytes of a byte slice.
+/// Loads an u64 using up to 7 bytes of a byte slice.
 ///
 /// Unsafe because: unchecked indexing at start..start+len
 #[inline]
diff --git a/src/librustc_data_structures/svh.rs b/src/librustc_data_structures/svh.rs
index 3757f921098..df4f6176837 100644
--- a/src/librustc_data_structures/svh.rs
+++ b/src/librustc_data_structures/svh.rs
@@ -17,7 +17,7 @@ pub struct Svh {
 }
 
 impl Svh {
-    /// Create a new `Svh` given the hash. If you actually want to
+    /// Creates a new `Svh` given the hash. If you actually want to
     /// compute the SVH from some HIR, you want the `calculate_svh`
     /// function found in `librustc_incremental`.
     pub fn new(hash: u64) -> Svh {
diff --git a/src/librustc_data_structures/transitive_relation.rs b/src/librustc_data_structures/transitive_relation.rs
index 39aed983360..0974607fabe 100644
--- a/src/librustc_data_structures/transitive_relation.rs
+++ b/src/librustc_data_structures/transitive_relation.rs
@@ -82,7 +82,7 @@ impl<T: Clone + Debug + Eq + Hash> TransitiveRelation<T> {
     }
 
     /// Applies the (partial) function to each edge and returns a new
-    /// relation.  If `f` returns `None` for any end-point, returns
+    /// relation. If `f` returns `None` for any end-point, returns
     /// `None`.
     pub fn maybe_map<F, U>(&self, mut f: F) -> Option<TransitiveRelation<U>>
         where F: FnMut(&T) -> Option<U>,
@@ -111,7 +111,7 @@ impl<T: Clone + Debug + Eq + Hash> TransitiveRelation<T> {
         }
     }
 
-    /// Check whether `a < target` (transitively)
+    /// Checks whether `a < target` (transitively)
     pub fn contains(&self, a: &T, b: &T) -> bool {
         match (self.index(a), self.index(b)) {
             (Some(a), Some(b)) => self.with_closure(|closure| closure.contains(a.0, b.0)),
@@ -122,7 +122,7 @@ impl<T: Clone + Debug + Eq + Hash> TransitiveRelation<T> {
     /// Thinking of `x R y` as an edge `x -> y` in a graph, this
     /// returns all things reachable from `a`.
     ///
-    /// Really this probably ought to be `impl Iterator<Item=&T>`, but
+    /// Really this probably ought to be `impl Iterator<Item = &T>`, but
     /// I'm too lazy to make that work, and -- given the caching
     /// strategy -- it'd be a touch tricky anyhow.
     pub fn reachable_from(&self, a: &T) -> Vec<&T> {
@@ -152,20 +152,20 @@ impl<T: Clone + Debug + Eq + Hash> TransitiveRelation<T> {
     /// the query is `postdom_upper_bound(a, b)`:
     ///
     /// ```text
-    /// // returns Some(x), which is also LUB
+    /// // Returns Some(x), which is also LUB.
     /// a -> a1 -> x
     ///            ^
     ///            |
     /// b -> b1 ---+
     ///
-    /// // returns Some(x), which is not LUB (there is none)
-    /// // diagonal edges run left-to-right
+    /// // Returns `Some(x)`, which is not LUB (there is none)
+    /// // diagonal edges run left-to-right.
     /// a -> a1 -> x
     ///   \/       ^
     ///   /\       |
     /// b -> b1 ---+
     ///
-    /// // returns None
+    /// // Returns `None`.
     /// a -> a1
     /// b -> b1
     /// ```
diff --git a/src/librustc_data_structures/work_queue.rs b/src/librustc_data_structures/work_queue.rs
index 06418b1051a..193025aafad 100644
--- a/src/librustc_data_structures/work_queue.rs
+++ b/src/librustc_data_structures/work_queue.rs
@@ -14,7 +14,7 @@ pub struct WorkQueue<T: Idx> {
 }
 
 impl<T: Idx> WorkQueue<T> {
-    /// Create a new work queue with all the elements from (0..len).
+    /// Creates a new work queue with all the elements from (0..len).
     #[inline]
     pub fn with_all(len: usize) -> Self {
         WorkQueue {
@@ -23,7 +23,7 @@ impl<T: Idx> WorkQueue<T> {
         }
     }
 
-    /// Create a new work queue that starts empty, where elements range from (0..len).
+    /// Creates a new work queue that starts empty, where elements range from (0..len).
     #[inline]
     pub fn with_none(len: usize) -> Self {
         WorkQueue {
@@ -54,7 +54,7 @@ impl<T: Idx> WorkQueue<T> {
         }
     }
 
-    /// True if nothing is enqueued.
+    /// Returns `true` if nothing is enqueued.
     #[inline]
     pub fn is_empty(&self) -> bool {
         self.deque.is_empty()