impl<I: Iterator> Peekable<I> {
/// Returns a reference to the next() value without advancing the iterator.
///
- /// The `peek()` method will return the value that a call to [`next()`] would
- /// return, but does not advance the iterator. Like [`next()`], if there is
- /// a value, it's wrapped in a `Some(T)`, but if the iterator is over, it
- /// will return `None`.
+ /// Like [`next()`], if there is a value, it is wrapped in a `Some(T)`.
+ /// But if the iteration is over, `None` is returned.
///
/// [`next()`]: trait.Iterator.html#tymethod.next
///
- /// Because `peek()` returns reference, and many iterators iterate over
- /// references, this leads to a possibly confusing situation where the
+ /// Because `peek()` returns a reference, and many iterators iterate over
+ /// references, there can be a possibly confusing situation where the
/// return value is a double reference. You can see this effect in the
- /// examples below, with `&&i32`.
+ /// examples below.
///
/// # Examples
///
///
/// assert_eq!(iter.next(), Some(&2));
///
- /// // we can peek() multiple times, the iterator won't advance
+ /// // The iterator does not advance even if we `peek` multiple times
/// assert_eq!(iter.peek(), Some(&&3));
/// assert_eq!(iter.peek(), Some(&&3));
///
/// assert_eq!(iter.next(), Some(&3));
///
- /// // after the iterator is finished, so is peek()
+ /// // After the iterator is finished, so is `peek()`
/// assert_eq!(iter.peek(), None);
/// assert_eq!(iter.next(), None);
/// ```
///
/// let mut iter = xs.iter().peekable();
///
- /// // there are still elements to iterate over
+ /// // There are still elements to iterate over
/// assert_eq!(iter.is_empty(), false);
///
- /// // let's consume the iterator
+ /// // Let's consume the iterator
/// iter.next();
/// iter.next();
/// iter.next();