Documentation for BufRead is confusing

[ouromoros]

rust/library/std/src/io/mod.rs

Lines 1886 to 1926 in a55748f

	#[stable(feature = "rust1", since = "1.0.0")]
	pub trait BufRead: Read {
	/// Returns the contents of the internal buffer, filling it with more data
	/// from the inner reader if it is 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.
	///
	/// [`consume`]: BufRead::consume
	///
	/// An empty buffer returned indicates that the stream has reached EOF.
	///
	/// # Errors
	///
	/// This function will return an I/O error if the underlying reader was
	/// read, but returned an error.
	///
	/// # Examples
	///
	/// A locked standard input implements `BufRead`:
	///
	/// ```no_run
	/// use std::io;
	/// use std::io::prelude::*;
	///
	/// let stdin = io::stdin();
	/// let mut stdin = stdin.lock();
	///
	/// let buffer = stdin.fill_buf().unwrap();
	///
	/// // work with buffer
	/// println!("{:?}", buffer);
	///
	/// // ensure the bytes we worked with aren't returned again later
	/// let length = buffer.len();
	/// stdin.consume(length);
	/// ```

The doc states thatfill_buf() needs to be paired with consume() to function properly, which can be comprehended to imply that if consume() is not called immediately after fill_buf() it would cause undefined behavior.

Also, it is said that later calling read may return the same contents. It's confusing that may is used instead of will here, and this confuses the reader to a deeper level.