From: Lukas Lueg <lukas.lueg@gmail.com>
Date: Fri, 27 Nov 2020 20:46:39 +0000 (+0100)
Subject: Expand docs on Peekable::peek_mut
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=08ec201c725ca86586fbb6b55f0a33272bd45d56;p=rust.git

Expand docs on Peekable::peek_mut
---

diff --git a/library/core/src/iter/adapters/peekable.rs b/library/core/src/iter/adapters/peekable.rs
index ebdc2555db2..2f8b9653c59 100644
--- a/library/core/src/iter/adapters/peekable.rs
+++ b/library/core/src/iter/adapters/peekable.rs
@@ -230,20 +230,24 @@ pub fn peek(&mut self) -> Option<&I::Item> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// #![feature(peekable_peek_mut)]
     /// let mut iter = [1, 2, 3].iter().peekable();
     ///
+    /// // Like with `peek()`, we can see into the future without advancing the iterator.
+    /// assert_eq!(iter.peek_mut(), Some(&mut &1));
     /// assert_eq!(iter.peek_mut(), Some(&mut &1));
     /// assert_eq!(iter.next(), Some(&1));
     ///
-    /// // Peek into the iterator and modify the value which will be returned next
-    /// if let Some(mut p) = iter.peek_mut() {
-    ///     if *p == &2 {
-    ///         *p = &5;
-    ///     }
+    /// // Peek into the iterator and set the value behind the mutable reference.
+    /// if let Some(p) = iter.peek_mut() {
+    ///     assert_eq!(*p, &2);
+    ///     *p = &5;
     /// }
     ///
+    /// // The value we put in reappears as the iterator continues.
     /// assert_eq!(iter.collect::<Vec<_>>(), vec![&5, &3]);
     /// ```
     #[inline]