Clarify iterator by_ref docs

Author: hkBst

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

@@ -1825,10 +1825,20 @@ pub trait Iterator {
         Inspect::new(self, f)
     }
 
-    /// Borrows an iterator, rather than consuming it.
+    /// Iterator adapter that turns ownership-taking methods into mutating methods.
     ///
-    /// 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),
+    /// take ownership (via a `self` parameter) of the iterator and then mutate it.
+    /// This method retuns a mutable reference to the original iterator,
+    /// that acts like the original iterator in all respects,
+    /// except that ownership-taking methods take ownership of the reference instead of of the original.
+    /// All mutation by ownership-taking methods will still mutate the original iterator.
+    ///
+    /// # Technical details
+    ///
+    /// The mutable reference that this method returns, implements the `Iterator` trait 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.
     ///
     /// # Examples
     ///
@@ -4019,6 +4029,7 @@ where
     }
 }
 
+/// Implements `Iterator` for mutable references to iterators, 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;