Rollup merge of #137890 - lolbinarycat:docs-bufreader-peek-consume, r=Mark-Simulacrum

doc: clarify that consume can be called after BufReader::peek

tracking issue #128405

library/std/src/io/buffered/bufreader.rs

@@ -109,9 +109,13 @@ impl<R: Read + ?Sized> BufReader<R> {
     ///
     /// `n` must be less than or equal to `capacity`.
     ///
-    /// the returned slice may be less than `n` bytes long if
+    /// The returned slice may be less than `n` bytes long if
     /// end of file is reached.
     ///
+    /// After calling this method, you may call [`consume`](BufRead::consume)
+    /// with a value less than or equal to `n` to advance over some or all of
+    /// the returned bytes.
+    ///
     /// ## Examples
     ///
     /// ```rust