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> {