Improve docs for collecting into Options

src/libcore/option.rs

@@ -1253,20 +1253,42 @@ impl<A, V: FromIterator<A>> FromIterator<Option<A>> for Option<V> {
     /// returned. Should no [`None`][Option::None] occur, a container with the
     /// values of each [`Option`] is returned.
     ///
-    /// Here is an example which increments every integer in a vector,
-    /// checking for overflow:
+    /// # Examples
+    ///
+    /// Here is an example which increments every integer in a vector.
+    /// `We use the checked variant of `add` that returns `None` when the
+    /// calculation would result in an overflow.
     ///
     /// ```
-    /// use std::u16;
+    /// let items = vec![0_u16, 1, 2];
+    ///
+    /// let res: Option<Vec<u16>> = items
+    ///     .iter()
+    ///     .map(|x| x.checked_add(1))
+    ///     .collect();
     ///
-    /// let v = vec![1, 2];
-    /// let res: Option<Vec<u16>> = v.iter().map(|&x: &u16|
-    ///     if x == u16::MAX { None }
-    ///     else { Some(x + 1) }
-    /// ).collect();
-    /// assert!(res == Some(vec![2, 3]));
+    /// assert_eq!(res, Some(vec![1, 2, 3]));
     /// ```
     ///
+    /// As you can see, this will return the expected, valid items.
+    ///
+    /// Here is another example that tries to subtract one from another list
+    /// of integers, this time checking for underflow:
+    ///
+    /// ```
+    /// let items = vec![2_u16, 1, 0];
+    ///
+    /// let res: Option<Vec<u16>> = items
+    ///     .iter()
+    ///     .map(|x| x.checked_sub(1))
+    ///     .collect();
+    ///
+    /// assert_eq!(res, None);
+    /// ```
+    ///
+    /// Since the last element is zero, it would underflow. Thus, the resulting
+    /// value is `None`.
+    ///
     /// [`Iterator`]: ../iter/trait.Iterator.html
     #[inline]
     fn from_iter<I: IntoIterator<Item=Option<A>>>(iter: I) -> Option<V> {