Rollup merge of #79478 - lukaslueg:peek_mut_docs, r=m-ou-se

Expand docs on Peekable::peek_mut

Slightly expand docs on `std::iter::Peekable::peek_mut`, tracked in #78302

r? `@m-ou-se`

Author: jonas-schievink

library/core/src/iter/adapters/peekable.rs

@@ -230,20 +230,24 @@ impl<I: Iterator> Peekable<I> {
     ///
     /// # 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]