The comment "the value passed on to the next iteration" confused me since it sounded more like what Haskell's [scanl](http://hackage.haskell.org/package/base-4.11.0.0/docs/Prelude.html#v:scanl) does where the closure's return value serves as both the "yielded value" *and* the new value of the "state".
I tried changing the example to make it clear that the closure's return value is decoupled from the state argument.
/// // each iteration, we'll multiply the state by the element
/// *state = *state * x;
///
/// // each iteration, we'll multiply the state by the element
/// *state = *state * x;
///
- /// // the value passed on to the next iteration
- /// Some(*state)
+ /// // then, we'll yield the negation of the state
+ /// Some(-*state)
- /// assert_eq!(iter.next(), Some(1));
- /// assert_eq!(iter.next(), Some(2));
- /// assert_eq!(iter.next(), Some(6));
+ /// assert_eq!(iter.next(), Some(-1));
+ /// assert_eq!(iter.next(), Some(-2));
+ /// assert_eq!(iter.next(), Some(-6));
/// assert_eq!(iter.next(), None);
/// ```
#[inline]
/// assert_eq!(iter.next(), None);
/// ```
#[inline]