Skip to content

Commit

Permalink
Standardize some usages of "which" in docstrings
Browse files Browse the repository at this point in the history
In US english, "that" is used in restrictive clauses in place of
"which", and often affects the meaning of sentences.

In UK english and many dialects, no distinction is
made.

While Rust devs want to avoid unproductive pedanticism, it is worth at
least being uniform in documentation such as:

http://doc.rust-lang.org/std/iter/index.html

and also in cases where correct usage of US english clarifies the
sentence.
  • Loading branch information
drewm1980 committed Dec 15, 2014
1 parent 126db54 commit 8fcc832
Show file tree
Hide file tree
Showing 6 changed files with 41 additions and 41 deletions.
2 changes: 1 addition & 1 deletion src/doc/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -4418,7 +4418,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}
Expand Down
2 changes: 1 addition & 1 deletion src/libcollections/ring_buf.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down
52 changes: 26 additions & 26 deletions src/libcore/iter.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
///
Expand All @@ -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
Expand Down Expand Up @@ -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.
///
Expand All @@ -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.
///
Expand All @@ -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
///
Expand All @@ -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
///
Expand All @@ -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.
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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> {
Expand Down Expand Up @@ -1441,7 +1441,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 {
Expand Down Expand Up @@ -1486,7 +1486,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> {
Expand Down Expand Up @@ -1534,7 +1534,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]
Expand Down Expand Up @@ -1648,7 +1648,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 {
Expand Down Expand Up @@ -1677,7 +1677,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 {
Expand Down Expand Up @@ -1714,7 +1714,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]
Expand Down Expand Up @@ -1782,7 +1782,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]
Expand Down Expand Up @@ -2075,7 +2075,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
///
Expand Down
4 changes: 2 additions & 2 deletions src/librand/lib.rs
Original file line number Diff line number Diff line change
@@ -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.
//
Expand Down Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions src/libstd/comm/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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> {
Expand Down
10 changes: 5 additions & 5 deletions src/libstd/io/fs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand All @@ -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<()> {
Expand Down Expand Up @@ -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|
Expand Down Expand Up @@ -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.
Expand All @@ -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>,
}
Expand Down

0 comments on commit 8fcc832

Please sign in to comment.