doc: Clarify EOF condition for AsyncReadExt::read_buf #3850
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
The current documentation for
read_buf
says:This confused me since I took "empty" to mean that the buffer had no readable data in it (like a vec with len() == 0).
I think part of the confusion is due to buffers like
bytes::BytesMut
using "empty" to refer to buffers that haveno readable data (i.e. a newly created buffer that hasn't been written to yet).
After reading the source code and chatting with @Darksonn it's clear that
Ok(0)
is returned when there's no moreroom in the buffer to write additional bytes. This is "empty" in the sense that an empty in the sense that an empty struct is,
but not in the sense that an empty vec is (which IMO is a closer mental model to a buffer).
Solution
I propose we change the above sentence to read:
The use of "remaining capacity" here is consistent with the phrasing
bytes::BytesMut
uses.