Merge pull request #19873 from drewm1980/master

Standardize some usages of "which" in docstrings

Reviewed-by: steveklabnik

src/doc/guide.md

@@ -4439,7 +4439,7 @@ for i in range(0u, nums.len()) {
 ```
 
 This is strictly worse than using an actual iterator. The `.iter()` method on
-vectors returns an iterator which iterates through a reference to each element
+vectors returns an iterator that iterates through a reference to each element
 of the vector in turn. So write this:
 
 ```{rust}

src/libcollections/ring_buf.rs

@@ -377,7 +377,7 @@ impl<T> RingBuf<T> {
         }
     }
 
-    /// Returns a front-to-back iterator which returns mutable references.
+    /// Returns a front-to-back iterator that returns mutable references.
     ///
     /// # Examples
     ///

src/libcore/iter.rs

@@ -110,8 +110,8 @@ pub trait Iterator<A> {
 #[unstable = "new convention for extension traits"]
 /// An extension trait providing numerous methods applicable to all iterators.
 pub trait IteratorExt<A>: Iterator<A> {
-    /// Chain this iterator with another, returning a new iterator which will
-    /// finish iterating over the current iterator, and then it will iterate
+    /// Chain this iterator with another, returning a new iterator that will
+    /// finish iterating over the current iterator, and then iterate
     /// over the other specified iterator.
     ///
     /// # Example
@@ -130,7 +130,7 @@ pub trait IteratorExt<A>: Iterator<A> {
         Chain{a: self, b: other, flag: false}
     }
 
-    /// Creates an iterator which iterates over both this and the specified
+    /// Creates an iterator that iterates over both this and the specified
     /// iterators simultaneously, yielding the two elements as pairs. When
     /// either iterator returns None, all further invocations of next() will
     /// return None.
@@ -151,7 +151,7 @@ pub trait IteratorExt<A>: Iterator<A> {
         Zip{a: self, b: other}
     }
 
-    /// Creates a new iterator which will apply the specified function to each
+    /// Creates a new iterator that will apply the specified function to each
     /// element returned by the first, yielding the mapped element instead.
     ///
     /// # Example
@@ -169,8 +169,8 @@ pub trait IteratorExt<A>: Iterator<A> {
         Map{iter: self, f: f}
     }
 
-    /// Creates an iterator which applies the predicate to each element returned
-    /// by this iterator. Only elements which have the predicate evaluate to
+    /// Creates an iterator that applies the predicate to each element returned
+    /// by this iterator. Only elements that have the predicate evaluate to
     /// `true` will be yielded.
     ///
     /// # Example
@@ -187,7 +187,7 @@ pub trait IteratorExt<A>: Iterator<A> {
         Filter{iter: self, predicate: predicate}
     }
 
-    /// Creates an iterator which both filters and maps elements.
+    /// Creates an iterator that both filters and maps elements.
     /// If the specified function returns None, the element is skipped.
     /// Otherwise the option is unwrapped and the new value is yielded.
     ///
@@ -205,7 +205,7 @@ pub trait IteratorExt<A>: Iterator<A> {
         FilterMap { iter: self, f: f }
     }
 
-    /// Creates an iterator which yields a pair of the value returned by this
+    /// Creates an iterator that yields a pair of the value returned by this
     /// iterator plus the current index of iteration.
     ///
     /// # Example
@@ -248,7 +248,7 @@ pub trait IteratorExt<A>: Iterator<A> {
         Peekable{iter: self, peeked: None}
     }
 
-    /// Creates an iterator which invokes the predicate on elements until it
+    /// Creates an iterator that invokes the predicate on elements until it
     /// returns false. Once the predicate returns false, all further elements are
     /// yielded.
     ///
@@ -268,7 +268,7 @@ pub trait IteratorExt<A>: Iterator<A> {
         SkipWhile{iter: self, flag: false, predicate: predicate}
     }
 
-    /// Creates an iterator which yields elements so long as the predicate
+    /// Creates an iterator that yields elements so long as the predicate
     /// returns true. After the predicate returns false for the first time, no
     /// further elements will be yielded.
     ///
@@ -287,8 +287,8 @@ pub trait IteratorExt<A>: Iterator<A> {
         TakeWhile{iter: self, flag: false, predicate: predicate}
     }
 
-    /// Creates an iterator which skips the first `n` elements of this iterator,
-    /// and then it yields all further items.
+    /// Creates an iterator that skips the first `n` elements of this iterator,
+    /// and then yields all further items.
     ///
     /// # Example
     ///
@@ -305,8 +305,8 @@ pub trait IteratorExt<A>: Iterator<A> {
         Skip{iter: self, n: n}
     }
 
-    /// Creates an iterator which yields the first `n` elements of this
-    /// iterator, and then it will always return None.
+    /// Creates an iterator that yields the first `n` elements of this
+    /// iterator, and then will always return None.
     ///
     /// # Example
     ///
@@ -324,7 +324,7 @@ pub trait IteratorExt<A>: Iterator<A> {
         Take{iter: self, n: n}
     }
 
-    /// Creates a new iterator which behaves in a similar fashion to fold.
+    /// Creates a new iterator that behaves in a similar fashion to fold.
     /// There is a state which is passed between each iteration and can be
     /// mutated as necessary. The yielded values from the closure are yielded
     /// from the Scan instance when not None.
@@ -1223,7 +1223,7 @@ impl<A, T: Clone + RandomAccessIterator<A>> RandomAccessIterator<A> for Cycle<T>
     }
 }
 
-/// An iterator which strings two iterators together
+/// An iterator that strings two iterators together
 #[deriving(Clone)]
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
@@ -1297,7 +1297,7 @@ for Chain<T, U> {
     }
 }
 
-/// An iterator which iterates two other iterators simultaneously
+/// An iterator that iterates two other iterators simultaneously
 #[deriving(Clone)]
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
@@ -1380,7 +1380,7 @@ RandomAccessIterator<(A, B)> for Zip<T, U> {
     }
 }
 
-/// An iterator which maps the values of `iter` with `f`
+/// An iterator that maps the values of `iter` with `f`
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
 pub struct Map<A, B, I: Iterator<A>, F: FnMut(A) -> B> {
@@ -1454,7 +1454,7 @@ impl<A, B, I, F> RandomAccessIterator<B> for Map<A, B, I, F> where
     }
 }
 
-/// An iterator which filters the elements of `iter` with `predicate`
+/// An iterator that filters the elements of `iter` with `predicate`
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
 pub struct Filter<A, I, P> where I: Iterator<A>, P: FnMut(&A) -> bool {
@@ -1512,7 +1512,7 @@ impl<A, I, P> DoubleEndedIterator<A> for Filter<A, I, P> where
     }
 }
 
-/// An iterator which uses `f` to both filter and map elements from `iter`
+/// An iterator that uses `f` to both filter and map elements from `iter`
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
 pub struct FilterMap<A, B, I, F> where I: Iterator<A>, F: FnMut(A) -> Option<B> {
@@ -1573,7 +1573,7 @@ impl<A, B, I, F> DoubleEndedIterator<B> for FilterMap<A, B, I, F> where
     }
 }
 
-/// An iterator which yields the current count and the element during iteration
+/// An iterator that yields the current count and the element during iteration
 #[deriving(Clone)]
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
@@ -1687,7 +1687,7 @@ impl<'a, A, T: Iterator<A>> Peekable<A, T> {
     }
 }
 
-/// An iterator which rejects elements while `predicate` is true
+/// An iterator that rejects elements while `predicate` is true
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
 pub struct SkipWhile<A, I, P> where I: Iterator<A>, P: FnMut(&A) -> bool {
@@ -1730,7 +1730,7 @@ impl<A, I, P> Iterator<A> for SkipWhile<A, I, P> where I: Iterator<A>, P: FnMut(
     }
 }
 
-/// An iterator which only accepts elements while `predicate` is true
+/// An iterator that only accepts elements while `predicate` is true
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
 pub struct TakeWhile<A, I, P> where I: Iterator<A>, P: FnMut(&A) -> bool {
@@ -1781,7 +1781,7 @@ impl<A, I, P> Iterator<A> for TakeWhile<A, I, P> where I: Iterator<A>, P: FnMut(
     }
 }
 
-/// An iterator which skips over `n` elements of `iter`.
+/// An iterator that skips over `n` elements of `iter`.
 #[deriving(Clone)]
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
@@ -1849,7 +1849,7 @@ impl<A, T: RandomAccessIterator<A>> RandomAccessIterator<A> for Skip<T> {
     }
 }
 
-/// An iterator which only iterates over the first `n` iterations of `iter`.
+/// An iterator that only iterates over the first `n` iterations of `iter`.
 #[deriving(Clone)]
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[stable]
@@ -2186,7 +2186,7 @@ impl<A, I, F> RandomAccessIterator<A> for Inspect<A, I, F> where
     }
 }
 
-/// An iterator which passes mutable state to a closure and yields the result.
+/// An iterator that passes mutable state to a closure and yields the result.
 ///
 /// # Example: The Fibonacci Sequence
 ///

src/librand/lib.rs

@@ -1,4 +1,4 @@
-// Copyright 2013 The Rust Project Developers. See the COPYRIGHT
+// Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -185,7 +185,7 @@ pub trait Rng {
         Rand::rand(self)
     }
 
-    /// Return an iterator which will yield an infinite number of randomly
+    /// Return an iterator that will yield an infinite number of randomly
     /// generated items.
     ///
     /// # Example

src/libstd/comm/mod.rs

@@ -81,7 +81,7 @@
 //! Shared usage:
 //!
 //! ```
-//! // Create a shared channel which can be sent along from many tasks
+//! // Create a shared channel that can be sent along from many tasks
 //! // where tx is the sending half (tx for transmission), and rx is the receiving
 //! // half (rx for receiving).
 //! let (tx, rx) = channel();
@@ -176,7 +176,7 @@
 // The choice of implementation of all channels is to be built on lock-free data
 // structures. The channels themselves are then consequently also lock-free data
 // structures. As always with lock-free code, this is a very "here be dragons"
-// territory, especially because I'm unaware of any academic papers which have
+// territory, especially because I'm unaware of any academic papers that have
 // gone into great length about channels of these flavors.
 //
 // ## Flavors of channels
@@ -190,7 +190,7 @@
 //              They contain as few atomics as possible and involve one and
 //              exactly one allocation.
 // * Streams - these channels are optimized for the non-shared use case. They
-//             use a different concurrent queue which is more tailored for this
+//             use a different concurrent queue that is more tailored for this
 //             use case. The initial allocation of this flavor of channel is not
 //             optimized.
 // * Shared - this is the most general form of channel that this module offers,
@@ -205,7 +205,7 @@
 // shared and concurrent queue holding all of the actual data.
 //
 // With two flavors of channels, two flavors of queues are also used. We have
-// chosen to use queues from a well-known author which are abbreviated as SPSC
+// chosen to use queues from a well-known author that are abbreviated as SPSC
 // and MPSC (single producer, single consumer and multiple producer, single
 // consumer). SPSC queues are used for streams while MPSC queues are used for
 // shared channels.
@@ -309,7 +309,7 @@
 //
 // Sadly this current implementation requires multiple allocations, so I have
 // seen the throughput of select() be much worse than it should be. I do not
-// believe that there is anything fundamental which needs to change about these
+// believe that there is anything fundamental that needs to change about these
 // channels, however, in order to support a more efficient select().
 //
 // # Conclusion
@@ -910,7 +910,7 @@ impl<T: Send> Receiver<T> {
         }
     }
 
-    /// Returns an iterator which will block waiting for messages, but never
+    /// Returns an iterator that will block waiting for messages, but never
     /// `panic!`. It will return `None` when the channel has hung up.
     #[unstable]
     pub fn iter<'a>(&'a self) -> Messages<'a, T> {

src/libstd/io/fs.rs

@@ -200,7 +200,7 @@ impl File {
              .update_desc("couldn't create file")
     }
 
-    /// Returns the original path which was used to open this file.
+    /// Returns the original path that was used to open this file.
     pub fn path<'a>(&'a self) -> &'a Path {
         &self.path
     }
@@ -215,7 +215,7 @@ impl File {
     }
 
     /// This function is similar to `fsync`, except that it may not synchronize
-    /// file metadata to the filesystem. This is intended for use case which
+    /// file metadata to the filesystem. This is intended for use cases that
     /// must synchronize content, but don't need the metadata on disk. The goal
     /// of this method is to reduce disk operations.
     pub fn datasync(&mut self) -> IoResult<()> {
@@ -456,7 +456,7 @@ pub fn symlink(src: &Path, dst: &Path) -> IoResult<()> {
 /// # Error
 ///
 /// This function will return an error on failure. Failure conditions include
-/// reading a file that does not exist or reading a file which is not a symlink.
+/// reading a file that does not exist or reading a file that is not a symlink.
 pub fn readlink(path: &Path) -> IoResult<Path> {
     fs_imp::readlink(path)
            .update_err("couldn't resolve symlink for path", |e|
@@ -546,7 +546,7 @@ pub fn readdir(path: &Path) -> IoResult<Vec<Path>> {
                        |e| format!("{}; path={}", e, path.display()))
 }
 
-/// Returns an iterator which will recursively walk the directory structure
+/// Returns an iterator that will recursively walk the directory structure
 /// rooted at `path`. The path given will not be iterated over, and this will
 /// perform iteration in some top-down order.  The contents of unreadable
 /// subdirectories are ignored.
@@ -557,7 +557,7 @@ pub fn walk_dir(path: &Path) -> IoResult<Directories> {
     })
 }
 
-/// An iterator which walks over a directory
+/// An iterator that walks over a directory
 pub struct Directories {
     stack: Vec<Path>,
 }