doc: Clarify EOF condition for AsyncReadExt::read_buf

[emesterhazy]

Motivation

The current documentation for read_buf says:

If the supplied buffer is not empty and the function returns Ok(0) then the source has reached an “end-of-file” event.

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 have
no 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 more
room 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:

If the remaining capacity of the supplied buffer is greater than 0 and the function returns Ok(0) then the source has reached an "end-of-file" event.

The use of "remaining capacity" here is consistent with the phrasing bytes::BytesMut uses.

[Darksonn]

I think it would read even better if we made a list with the two cases like we do on AsyncReadExt::read.

[emesterhazy]

👍 I pulled the comment down from read, but changed the second point for read_buf because I think the concept of "remaining capacity" makes more sense for BufMut than length since a BufMut has the concept of initialized length and uninitialized remaining capacity.

Here's the change for that line:

- 2. The buffer specified was 0 bytes in length.
+ 2. The buffer specified had a remaining capacity of zero.

[Darksonn]

The BufMut trait has no len method.

[emesterhazy]

Ah, you're right. I'll update.

[Darksonn]

Thanks!