Rollup merge of rust-lang#136177 - hkBst:patch-24, r=ibraheemdev

clarify BufRead::{fill_buf, consume} docs

Fixes rust-lang#85394

Author: matthiaskrgr

std/src/io/mod.rs

@@ -2251,24 +2251,18 @@ fn skip_until<R: BufRead + ?Sized>(r: &mut R, delim: u8) -> Result<usize> {
 #[stable(feature = "rust1", since = "1.0.0")]
 #[cfg_attr(not(test), rustc_diagnostic_item = "IoBufRead")]
 pub trait BufRead: Read {
-    /// Returns the contents of the internal buffer, filling it with more data
-    /// from the inner reader if it is empty.
+    /// Returns the contents of the internal buffer, filling it with more data, via `Read` methods, if empty.
     ///
-    /// This function is a lower-level call. It needs to be paired with the
-    /// [`consume`] method to function properly. When calling this
-    /// method, none of the contents will be "read" in the sense that later
-    /// calling `read` may return the same contents. As such, [`consume`] must
-    /// be called with the number of bytes that are consumed from this buffer to
-    /// ensure that the bytes are never returned twice.
+    /// This is a lower-level method and is meant to be used together with [`consume`],
+    /// which can be used to mark bytes that should not be returned by subsequent calls to `read`.
     ///
     /// [`consume`]: BufRead::consume
     ///
-    /// An empty buffer returned indicates that the stream has reached EOF.
+    /// Returns an empty buffer when the stream has reached EOF.
     ///
     /// # Errors
     ///
-    /// This function will return an I/O error if the underlying reader was
-    /// read, but returned an error.
+    /// This function will return an I/O error if a `Read` method was called, but returned an error.
     ///
     /// # Examples
     ///
@@ -2286,26 +2280,21 @@ pub trait BufRead: Read {
     /// // work with buffer
     /// println!("{buffer:?}");
     ///
-    /// // ensure the bytes we worked with aren't returned again later
+    /// // mark the bytes we worked with as read
     /// let length = buffer.len();
     /// stdin.consume(length);
     /// # std::io::Result::Ok(())
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     fn fill_buf(&mut self) -> Result<&[u8]>;
 
-    /// Tells this buffer that `amt` bytes have been consumed from the buffer,
-    /// so they should no longer be returned in calls to `read`.
+    /// Marks the given `amount` of additional bytes from the internal buffer as having been read.
+    /// Subsequent calls to `read` only return bytes that have not been marked as read.
     ///
-    /// This function is a lower-level call. It needs to be paired with the
-    /// [`fill_buf`] method to function properly. This function does
-    /// not perform any I/O, it simply informs this object that some amount of
-    /// its buffer, returned from [`fill_buf`], has been consumed and should
-    /// no longer be returned. As such, this function may do odd things if
-    /// [`fill_buf`] isn't called before calling it.
+    /// This is a lower-level method and is meant to be used together with [`fill_buf`],
+    /// which can be used to fill the internal buffer via `Read` methods.
     ///
-    /// The `amt` must be `<=` the number of bytes in the buffer returned by
-    /// [`fill_buf`].
+    /// It is a logic error if `amount` exceeds the number of unread bytes in the internal buffer, which is returned by [`fill_buf`].
     ///
     /// # Examples
     ///
@@ -2314,9 +2303,9 @@ pub trait BufRead: Read {
     ///
     /// [`fill_buf`]: BufRead::fill_buf
     #[stable(feature = "rust1", since = "1.0.0")]
-    fn consume(&mut self, amt: usize);
+    fn consume(&mut self, amount: usize);
 
-    /// Checks if the underlying `Read` has any data left to be read.
+    /// Checks if there is any data left to be `read`.
     ///
     /// This function may fill the buffer to check for data,
     /// so this functions returns `Result<bool>`, not `bool`.
@@ -2325,6 +2314,10 @@ pub trait BufRead: Read {
     /// returned slice is empty (which means that there is no data left,
     /// since EOF is reached).
     ///
+    /// # Errors
+    ///
+    /// This function will return an I/O error if a `Read` method was called, but returned an error.
+    ///
     /// Examples
     ///
     /// ```