---

yaml
---
r: 55647
b: refs/heads/master
c: a2e5350
h: refs/heads/master
i:
  55645: ffd364a
  55643: 3b42666
  55639: a5519e9
  55631: c8f067e
  55615: 792c05f
v: v3

Author: thestinger

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 1d81b7b286d2be46474022935c5ac111dafd5c4d
+refs/heads/master: a2e535028471b715b5a3aaf7cbeb3e6d77a07af6
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: 79a2b2eafc3c766cecec8a5f76317693bae9ed17
 refs/heads/try: 8eb2bab100b42f0ba751552d8eff00eb2134c55a

trunk/src/libcore/iterator.rs

@@ -8,7 +8,14 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Composable iterator objects
+/*! Composable external iterators
+
+The `Iterator` trait defines an interface for objects which implement iteration as a state machine.
+
+Algorithms like `zip` are provided as `Iterator` implementations which wrap other objects
+implementing the `Iterator` trait.
+
+*/
 
 use prelude::*;
 
@@ -17,6 +24,10 @@ pub trait Iterator<A> {
     fn next(&mut self) -> Option<A>;
 }
 
+/// Iterator adaptors provided for every `Iterator` implementation. The adaptor objects are also
+/// implementations of the `Iterator` trait.
+///
+/// In the future these will be default methods instead of a utility trait.
 pub trait IteratorUtil<A> {
     fn chain(self, other: Self) -> ChainIterator<Self>;
     fn zip<B, U: Iterator<B>>(self, other: U) -> ZipIterator<Self, U>;
@@ -31,6 +42,10 @@ pub trait IteratorUtil<A> {
     fn advance(&mut self, f: &fn(A) -> bool);
 }
 
+/// Iterator adaptors provided for every `Iterator` implementation. The adaptor objects are also
+/// implementations of the `Iterator` trait.
+///
+/// In the future these will be default methods instead of a utility trait.
 impl<A, T: Iterator<A>> IteratorUtil<A> for T {
     #[inline(always)]
     fn chain(self, other: T) -> ChainIterator<T> {