sync: improve the docs for recv_many

[SwishSwushPow]

Trying to explain a bit better when recv_many will return and why in some cases the returned number of received messages is below the input parameter limit.

Motivation

I stumbled upon recv_many for the first time ever in a bit of code while reviewing a PR. I took some issue with how the function was called (inside a while loop) and had a look at the docs to understand why that would be necessary. When reading through the docs it seemed to me as if there was seemingly no need for a loop because recv_many would apparently wait for new messages if none were available, only returning when the limit would be reached or the channel would be closed. I gave this a try in a smaller code example and had to realize that this was not the case. Looking at the source I found that recv_many would only wait for the first message, but would return early if the channel queue had no messages available after that, even when not being closed. At this point I felt that the docs were a bit unclear in that regard.

Solution

By describing the behavior a bit more explicitly I am hoping to improve the docs and avoid misunderstandings like mine in the future.

[Darksonn]

If I'm skimming this, I'm going to see "return when the number of received messages reaches limit" and I will get the wrong impression. I agree the current docs are bad, but I don't think this wording is good either.

[SwishSwushPow]

Could you please give me a hint in which way the current wording isn't up to par? Otherwise I'm not sure in which direction to go with this. 😅

[Darksonn]

How about something like this?

Receives between 1 and `limit` messages into `buffer`.

This method is intended as a performance optimization for cases where
you wish to process messages in batches. The method may return less than
`limit` messages, so `recv_many` can *not* be used to receive a fixed
number of messages in one call.

This method waits until at least one message is available, and then
receives as many messages as it can into `buffer` efficiently. The
number of messages added to `buffer` is returned, and this number will
often be less than `limit` even if the channel is still open.

For non-zero values of `limit`, this method will never return `0` unless
the channel has been closed and there are no remaining messages in the
channel's queue. This indicates that no further values can ever be
received from this `Receiver`. The channel is closed when all senders
have been dropped, or when [`close`] is called.

Note that if [`close`] is called, but there are still outstanding
[`Permits`] from before it was closed, the channel is not considered
closed by `recv_many` until the permits are used or dropped.

The capacity of `buffer` is increased as needed.

[SwishSwushPow]

Little bump here. Anything I can do to improve the state of this PR? :)