Apply suggestions from code review

Improve documentation for `PeekableIterator` to reflect the changes in API

Co-authored-by: +merlan #flirora <[email protected]>

Author: wmstack

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

@@ -1,20 +1,20 @@
 #[unstable(feature = "peekable_iterator", issue = "132973")]
-/// Iterators which inherently support `peek()` without needing to be wrapped by a `Peekable`.
+/// Iterators which inherently support peeking without needing to be wrapped by a `Peekable`.
 pub trait PeekableIterator: Iterator {
-    /// executes the closure with an Option containing `None` if the iterator is exhausted or Some(&Self::Item)
+    /// Executes the closure with a reference to the `next()` value without advancing the iterator.
     fn peek_with<T>(&mut self, func: impl for<'a> FnOnce(Option<&'a Self::Item>) -> T) -> T;
 
-    /// executes the closure on the next element without advancing the iterator, or returns None if the iterator is exhausted.
+    /// Executes the closure on the `next()` element without advancing the iterator, or returns `None` if the iterator is exhausted.
     fn peek_map<T>(&mut self, func: impl for<'a> FnOnce(&'a Self::Item) -> T) -> Option<T> {
         self.peek_with(|x| x.map(|y| func(y)))
     }
 
-    /// returns the `next()` element if a predicate holds true
+    /// Returns the `next()` element if the given predicate holds true.
     fn next_if(&mut self, func: impl FnOnce(&Self::Item) -> bool) -> Option<Self::Item> {
         self.peek_map(func).and_then(|_| self.next())
     }
 
-    /// move forward and return the `next()` item if it is equal to the expected value
+    /// Moves forward and return the `next()` item if it is equal to the expected value.
     fn next_if_eq<T>(&mut self, expected: &T) -> Option<Self::Item>
     where
         Self::Item: PartialEq<T>,