sync: improve the docs for recv_many

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`.

Additionally the docs for the bounded and unbounded `recv_many` are adjusted to match.

Author: SwishSwushPow

tokio/src/sync/mpsc/bounded.rs

@@ -248,12 +248,17 @@ impl<T> Receiver<T> {
     /// as specified by `limit`. If `limit` is zero, the function immediately
     /// returns `0`. The return value is the number of values added to `buffer`.
     ///
-    /// For `limit > 0`, if there are no messages in the channel's queue, but
-    /// the channel has not yet been closed, this method will sleep until a
-    /// message is sent or the channel is closed. 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 released.
+    /// For `limit > 0`: If there are no messages in the channels' queue initially,
+    /// `recv_many` will sleep until a first message is received. After that, it will
+    ///
+    /// * Return when the number of received messages reaches `limit`.
+    /// * Return earlier when the channel is closed or no further messages area
+    /// available in the channel at the time. In these cases,
+    /// the number of received messages can be lower than `limit`.
+    ///
+    /// 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 released.
     ///
     /// 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

tokio/src/sync/mpsc/unbounded.rs

@@ -173,13 +173,20 @@ impl<T> UnboundedReceiver<T> {
     /// Receives the next values for this receiver and extends `buffer`.
     ///
     /// This method extends `buffer` by no more than a fixed number of values
-    /// as specified by `limit`. If `limit` is zero, the function returns
-    /// immediately with `0`. The return value is the number of values added to
-    /// `buffer`.
+    /// as specified by `limit`. If `limit` is zero, the function immediately
+    /// returns `0`. The return value is the number of values added to `buffer`.
     ///
-    /// For `limit > 0`, if there are no messages in the channel's queue,
-    /// but the channel has not yet been closed, this method will sleep
-    /// until a message is sent or the channel is closed.
+    /// For `limit > 0`: If there are no messages in the channels' queue initially,
+    /// `recv_many` will sleep until a first message is received. After that, it will
+    ///
+    /// * Return when the number of received messages reaches `limit`.
+    /// * Return earlier when the channel is closed or no further messages area
+    /// available in the channel at the time. In these cases,
+    /// the number of received messages can be lower than `limit`.
+    ///
+    /// 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 released.
     ///
     /// 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
@@ -197,6 +204,7 @@ impl<T> UnboundedReceiver<T> {
     /// channel.
     ///
     /// [`close`]: Self::close
+    /// [`Permits`]: struct@crate::sync::mpsc::Permit
     ///
     /// # Examples
     ///