Auto merge of #33016 - tbu-:pr_doc_peekable, r=alexcrichton

Add a note about side effects for "peekable" iterators

1 files changed, 7 insertions, 2 deletions

diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index b4378a5fec5..69f10d197f7 100644
--- a/src/libcore/iter.rs
+++ b/src/libcore/iter.rs
@@ -901,12 +901,17 @@ pub trait Iterator {
         Enumerate { iter: self, count: 0 }
     }
 
-    /// Creates an iterator which can look at the `next()` element without
-    /// consuming it.
+    /// Creates an iterator which can use `peek` to look at the next element of
+    /// the iterator without consuming it.
     ///
     /// Adds a [`peek()`] method to an iterator. See its documentation for
     /// more information.
     ///
+    /// Note that the underlying iterator is still advanced when `peek` is
+    /// called for the first time: In order to retrieve the next element,
+    /// `next` is called on the underlying iterator, hence any side effects of
+    /// the `next` method will occur.
+    ///
     /// [`peek()`]: struct.Peekable.html#method.peek
     ///
     /// # Examples