diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index 6ba0f7c3a157543d3b4968b5476bdbed642ae4d9..7706d01cbaed6bb3ee85d5994fa6359060866142 100644
--- a/src/libcore/iter.rs
+++ b/src/libcore/iter.rs
@@ -99,9 +99,10 @@ pub trait Iterator {
/// Advance the iterator and return the next value. Return `None` when the end is reached.
fn next(&mut self) -> Option;
- /// Return a lower bound and upper bound on the remaining length of the iterator.
+ /// Returns a lower and upper bound on the remaining length of the iterator.
///
- /// The common use case for the estimate is pre-allocating space to store the results.
+ /// An upper bound of `None` means either there is no known upper bound, or the upper bound
+ /// does not fit within a `uint`.
#[inline]
fn size_hint(&self) -> (uint, Option) { (0, None) }
@@ -644,6 +645,9 @@ fn min_by(&mut self, f: |&A| -> B) -> Option {
}
/// A range iterator able to yield elements from both ends
+///
+/// A `DoubleEndedIterator` can be thought of as a deque in that `next()` and `next_back()` exhaust
+/// elements from the *same* range, and do not work independently of each other.
pub trait DoubleEndedIterator: Iterator {
/// Yield an element from the end of the range, returning `None` if the range is empty.
fn next_back(&mut self) -> Option;
@@ -690,12 +694,15 @@ fn reverse_(&mut self) {
/// An object implementing random access indexing by `uint`
///
/// A `RandomAccessIterator` should be either infinite or a `DoubleEndedIterator`.
+/// Calling `next()` or `next_back()` on a `RandomAccessIterator`
+/// reduces the indexable range accordingly. That is, `it.idx(1)` will become `it.idx(0)`
+/// after `it.next()` is called.
pub trait RandomAccessIterator: Iterator {
/// Return the number of indexable elements. At most `std::uint::MAX`
/// elements are indexable, even if the iterator represents a longer range.
fn indexable(&self) -> uint;
- /// Return an element at an index
+ /// Return an element at an index, or `None` if the index is out of bounds
fn idx(&mut self, index: uint) -> Option;
}