Clarify iterator by_ref docs

Author: hkBst

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

@@ -1825,10 +1825,24 @@ pub trait Iterator {
         Inspect::new(self, f)
     }
 
-    /// Borrows an iterator, rather than consuming it.
-    ///
-    /// This is useful to allow applying iterator adapters while still
-    /// retaining ownership of the original iterator.
+    /// Most `Iterator` methods, other than the `next` method (and this one),
+    /// are consuming methods; they move the iterator, taking ownership of it,
+    /// via their `self` parameter (and then mutating it privately).
+    /// Usually, this is fine, though sometimes you want to
+    /// mutate the original iterator without giving up ownership of it.
+    /// That is where this method comes in.
+    ///
+    /// The return value of this method acts like the original iterator,
+    /// except that all consuming methods behave like mutating methods,
+    /// which mutate the original iterator, without taking ownership of it.
+    ///
+    /// This works, because the mutable reference that this method returns,
+    /// implements the `Iterator` trait in its own right via:
+    /// [impl<I: Iterator + ?Sized> Iterator for &mut I { type Item = I::Item; ...}](trait.Iterator.html#impl-Iterator-for-%26mut I).
+    /// This implementation simply passes all method calls on to the original iterator,
+    /// allowing you to call a consuming iterator method on the mutable reference,
+    /// which will mutate the original,
+    /// without giving up ownership of the original iterator.
     ///
     /// # Examples
     ///
@@ -4019,6 +4033,7 @@ where
     }
 }
 
+/// Implements Iterator for mutable references to Iterator, such as those produced by [Iterator::by_ref]
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<I: Iterator + ?Sized> Iterator for &mut I {
     type Item = I::Item;