sync: clarify the behavior of mpsc::Receiver::recv_many()

Co-authored-by: Alice Ryhl <[email protected]>
Signed-off-by: ADD-SP <[email protected]>

Author: ADD-SP

tokio/src/sync/mpsc/bounded.rs

@@ -244,24 +244,34 @@ impl<T> Receiver<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 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 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.
-    ///
-    /// The capacity of `buffer` is increased as needed.
+    /// This method is a more efficient version of the following implementation.
+    /// ```
+    /// async fn recv_many(&mut self, buffer: &mut Vec<T>, limit: usize) -> usize {
+    ///     if limit == 0 {
+    ///         return 0;
+    ///     }
+    ///
+    ///     // Wait for at least one message (or channel close).
+    ///     let Some(first_message) = self.recv().await else {
+    ///         return 0;
+    ///     };
+    ///
+    ///     buffer.push(first_message);
+    ///     let mut num_pushed = 1;
+    ///
+    ///     // Try to get more messages, but don't sleep.
+    ///     while num_pushed < limit {
+    ///         if let Some(msg) = self.try_recv() {
+    ///             buffer.push(msg);
+    ///             num_pushed += 1;
+    ///         } else {
+    ///             break;
+    ///         }
+    ///     }
+    ///
+    ///     num_pushed
+    /// }
+    /// ```
     ///
     /// # Cancel safety
     ///