Updated the Iterator docs with information about overriding methods.

diff --git a/src/libcore/iter/mod.rs b/src/libcore/iter/mod.rs
index 1601357d3b05400199dc9c8326a9fd4f333eaca9..6eccb9d1ea86d294c9527dff5361fd870f1d89b7 100644 (file)
--- a/src/libcore/iter/mod.rs
+++ b/src/libcore/iter/mod.rs
@@ -140,6 +140,11 @@
 //! call `next()` on your iterator, until it reaches `None`. Let's go over that
 //! next.
 //!
+//! Also note that `Iterator` provides a default implementation of methods such as `nth` and `fold`
+//! which call `next` internally. However, it is also possible to write a custom implementation of
+//! methods like `nth` and `fold` if an iterator can compute them more efficiently without calling
+//! `next`.
+//!
 //! # for Loops and IntoIterator
 //!
 //! Rust's `for` loop syntax is actually sugar for iterators. Here's a basic

diff --git a/src/libcore/iter/traits/iterator.rs b/src/libcore/iter/traits/iterator.rs
index 403f3358105325c917fae4fa0277f4dc7be5700e..062a7f7043de5ac2c84c9de6ccbc9bed5f45c994 100644 (file)
--- a/src/libcore/iter/traits/iterator.rs
+++ b/src/libcore/iter/traits/iterator.rs
@@ -964,6 +964,7 @@ fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> where
     /// Creates an iterator that skips the first `n` elements.
     ///
     /// After they have been consumed, the rest of the elements are yielded.
+    /// Rather than overriding this method directly, instead override the `nth` method.
     ///
     /// # Examples
     ///