Improve Iterator::by_ref example

library/core/src/iter/traits/iterator.rs

@@ -1535,34 +1535,32 @@ pub trait Iterator {
  ///
  /// # Examples
  ///
- /// Basic usage:
+ /// This demonstrates a use case that needs `by_ref`:
  ///
- /// ```
- /// let a = [1, 2, 3];
- ///
- /// let iter = a.iter();
- ///
- /// let sum: i32 = iter.take(5).fold(0, |acc, i| acc + i);
+ /// ```compile_fail,E0382
+ /// let a = [1, 2, 3, 4, 5];
+ /// let mut iter = a.iter();
+ /// let sum: i32 = iter.take(3).fold(0, |acc, i| acc + i);
  ///
  /// assert_eq!(sum, 6);
  ///
- /// // if we try to use iter again, it won't work. The following line
- /// // gives "error: use of moved value: `iter`
- /// // assert_eq!(iter.next(), None);
+ /// // Error! We can't use `iter` again because it was moved
+ /// // by `take`.
+ /// assert_eq!(iter.next(), Some(&4));
+ /// ```
  ///
- /// // let's try that again
- /// let a = [1, 2, 3];
+ /// Now, let's use `by_ref` to make this work:
  ///
+ /// ```
+ /// let a = [1, 2, 3, 4, 5];
  /// let mut iter = a.iter();
+ /// // We add in a call to `by_ref` here so `iter` isn't moved.
+ /// let sum: i32 = iter.by_ref().take(3).fold(0, |acc, i| acc + i);
  ///
- /// // instead, we add in a .by_ref()
- /// let sum: i32 = iter.by_ref().take(2).fold(0, |acc, i| acc + i);
- ///
- /// assert_eq!(sum, 3);
+ /// assert_eq!(sum, 6);
  ///
- /// // now this is just fine:
- /// assert_eq!(iter.next(), Some(&3));
- /// assert_eq!(iter.next(), None);
+ /// // And now we can use `iter` again because we still own it.
+ /// assert_eq!(iter.next(), Some(&4));
  /// ```
  #[stable(feature = "rust1", since = "1.0.0")]
  fn by_ref(&mut self) -> &mut Self