rollup merge of #19512: cybergeek94/master

Added the example from [this Reddit thread][1], reworked to be more robust with correct logic (first link skipped the 0th and 1st Fibonacci numbers, second forgot about the last two valid values before overflow). Will yield all Fibonacci numbers sequentially in the range `[0, <u32 as Int>::max_value())`.

If the example is too complicated I can change it to a more naive version, perhaps using signed integers to check for overflow instead of `Option` and `.checked_add()`.

Also reworded the doc comments to clarify the usage and behavior of `Unfold`, as the thread suggested that it wasn't really clear how `Unfold` worked and when one should use it.

This change is in the `core` crate but I based the example on `std` since that's where most readers will find the example. I included a note about `core` for clarity. Edit: removed.

Tested with `rustdoc src/libcore/lib.rs`. Rebased against latest master as of the creation of this PR.

[1]: http://www.reddit.com/r/rust/comments/2ny8r1/a_question_about_loops/cmighu4?context=10000

src/libcore/iter.rs

@@ -2036,18 +2036,49 @@ for Inspect<'a, A, T> {
     }
 }
 
-/// An iterator which just modifies the contained state throughout iteration.
+/// An iterator which passes mutable state to a closure and yields the result.
+///
+/// # Example: The Fibonacci Sequence
+///
+/// An iterator that yields sequential Fibonacci numbers, and stops on overflow.
+///
+/// ```rust
+/// use std::iter::Unfold;
+/// use std::num::Int; // For `.checked_add()`
+///
+/// // This iterator will yield up to the last Fibonacci number before the max value of `u32`.
+/// // You can simply change `u32` to `u64` in this line if you want higher values than that.
+/// let mut fibonacci = Unfold::new((Some(0u32), Some(1u32)), |&(ref mut x2, ref mut x1)| {
+///     // Attempt to get the next Fibonacci number
+///     // `x1` will be `None` if previously overflowed.
+///     let next = match (*x2, *x1) {
+///         (Some(x2), Some(x1)) => x2.checked_add(x1),
+///         _ => None,
+///     };
+///
+///     // Shift left: ret <- x2 <- x1 <- next
+///     let ret = *x2;
+///     *x2 = *x1;
+///     *x1 = next;
+///
+///     ret
+/// });
+///
+/// for i in fibonacci {
+///     println!("{}", i);
+/// }
+/// ```
 #[experimental]
 pub struct Unfold<'a, A, St> {
     f: |&mut St|: 'a -> Option<A>,
-    /// Internal state that will be yielded on the next iteration
+    /// Internal state that will be passed to the closure on the next iteration
     pub state: St,
 }
 
 #[experimental]
 impl<'a, A, St> Unfold<'a, A, St> {
     /// Creates a new iterator with the specified closure as the "iterator
-    /// function" and an initial state to eventually pass to the iterator
+    /// function" and an initial state to eventually pass to the closure
     #[inline]
     pub fn new<'a>(initial_state: St, f: |&mut St|: 'a -> Option<A>)
                -> Unfold<'a, A, St> {