Change:
/// #[stable(feature = "rust1", since = "1.0.0")] pub trait BufRead: Read { <del> /// Fills the internal buffer of this object, returning the buffer contents. </del> <ins> /// Returns the contents of the internal buffer, filling it with more data /// from the inner reader if it is empty. </ins> /// /// This function is a lower-level call. It needs to be paired with the /// [`consume`] method to function properly. When calling this

Discussion:
Would you like to fix this bug? If so, . The documentation currently states that : However, this is not what 's of that method does. It will only fill the buffer if no data is currently buffered. If data is already present in the buffer, no filling takes place: I would argue that the current behavior of 's implementation is usually what users would want to do, but if does not match the documentation of, nor the name of, . I don't know what the right solution here is, but I suspect the only safe thing to do would be to update 's implementation to match the docs (i.e., to make it actually fill its buffer), and then to add another method to (perhaps ?) that gives the currently buffered contents, regardless of the amount of buffered data, and without reading from the underlying .
Adding a method to would be a breaking change unless you have a suitable default implementation in mind. I would love it if we can make "every time this is called, the implementation should fetch more data" part of the API contract because it's easy to get burned when you make that assumption with . The only one impl I know of where this guarantee isn't really feasible is which can only return buffers from one source at a time.
Well, even that is tricky, right? What if the buffer is already full? I also think there's value in being able to get access to the bytes currently in the buffer without doing a syscall (something like ).
The issue is that you can't really do anything to the structure of the trait at this point without breaking changes, though this is now feasible with epochs. Adding extra functionality directly to is quite a bit more reasonable though. I have that I couldn't be bothered to champion and instead just .
I guess one question is where we decide to not expand and say that external crates should provide features instead. I'd advocate for this being something should support (though as you say, possibly not ).
I also ran into this 'faulty' documentation issue. I have a program which needed pushing back data on the reader and by reading the documentation I thought I could use fillbuf with consume for that, but found out the hard way that fillbuf isn't actually filling the buffer but returning the existing buffer if something is still in there. Hardly appreciated if the fill_buf acts as documented.
The proposed behavior is fundamentally broken.

Imagine a being used to parse some line-oriented protocol. The BufReader's buffer capacity is 4096 bytes, and the peer sends a single TCP packet with 2 lines in 100 bytes. It then expects our end to respond, so it's not doing any more writes. You call , which calls into . Since this is a new , the buffer is empty so it calls down into the and reads all 100 bytes into the buffer. then returns the first line, and there's the one remaining line in the buffer. Now you call again to read the last line the peer sent over. With the current behavior, the 's buffer is nonempty, so immediately returns it. returns the last line our end responds to the peer, and everything is happy. With the proposed behavior, calls back down into the since its buffer isn't full and the protocol deadlocks.
Just to clarify, is the idea here to update the docs from: Fills the internal buffer of this object, returning the buffer contents. something like this?
Ah, commented while I was writing my comment and answered a couple of the questions I had
I'd probably phrase it as
I agree with you that changing the behavior of seems wrong. As pointed out in the original post: "the current behavior of 's implementation is usually what users would want to do, but if does not match the documentation of, nor the name of, ". I do think there's an argument for providing a method that gives the buffer contents without ever doing a syscall, but that's probably an argument for another issue.
I'm happy to mentor anyone who wants to fix this issue! Here's how: The line in question is here: This should be changed to: I'm happy to answer any additional questions!
Perhaps we should also include a reference to the newly ()? Though I suppose that is (sadly) only available for and not all .