sync: improve bounded mpsc documentation (#3458)

tokio/src/sync/mpsc/bounded.rs

@@ -108,8 +108,21 @@ impl<T> Receiver<T> {
 
     /// Receives the next value for this receiver.
     ///
-    /// `None` is returned when all `Sender` halves have dropped, indicating
-    /// that no further values can be sent on the channel.
+    /// This method returns `None` if the channel has been closed and there are
+    /// no remaining messages in the channel's buffer. 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.
+    ///
+    /// If there are no messages in the channel's buffer, 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` until the permits are released.
+    ///
+    /// [`close`]: Self::close
+    /// [`Permits`]: struct@crate::sync::mpsc::Permit
     ///
     /// # Examples
     ///
@@ -152,6 +165,27 @@ impl<T> Receiver<T> {
 
     /// Blocking receive to call outside of asynchronous contexts.
     ///
+    /// This method returns `None` if the channel has been closed and there are
+    /// no remaining messages in the channel's buffer. 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.
+    ///
+    /// If there are no messages in the channel's buffer, but the channel has
+    /// not yet been closed, this method will block until a message is sent or
+    /// the channel is closed.
+    ///
+    /// This method is intended for use cases where you are sending from
+    /// asynchronous code to synchronous code, and will work even if the sender
+    /// is not using [`blocking_send`] to send the message.
+    ///
+    /// Note that if [`close`] is called, but there are still outstanding
+    /// [`Permits`] from before it was closed, the channel is not considered
+    /// closed by `blocking_recv` until the permits are released.
+    ///
+    /// [`close`]: Self::close
+    /// [`Permits`]: struct@crate::sync::mpsc::Permit
+    /// [`blocking_send`]: fn@crate::sync::mpsc::Sender::blocking_send
+    ///
     /// # Panics
     ///
     /// This function panics if called within an asynchronous execution
@@ -201,14 +235,16 @@ impl<T> Receiver<T> {
         self.chan.try_recv()
     }
 
-    /// Closes the receiving half of a channel, without dropping it.
+    /// Closes the receiving half of a channel without dropping it.
     ///
     /// This prevents any further messages from being sent on the channel while
     /// still enabling the receiver to drain messages that are buffered. Any
     /// outstanding [`Permit`] values will still be able to send messages.
     ///
-    /// In order to guarantee no messages are dropped, after calling `close()`,
-    /// `recv()` must be called until `None` is returned.
+    /// To guarantee that no messages are dropped, after calling `close()`,
+    /// `recv()` must be called until `None` is returned. If there are
+    /// outstanding [`Permit`] values, the `recv` method will not return `None`
+    /// until those are released.
     ///
     /// [`Permit`]: Permit
     ///
@@ -360,7 +396,7 @@ impl<T> Sender<T> {
     ///         tx4.closed(),
     ///         tx5.closed()
     ///     );
-    ////     println!("Receiver dropped");
+    ///     println!("Receiver dropped");
     /// }
     /// ```
     pub async fn closed(&self) {
@@ -505,6 +541,12 @@ impl<T> Sender<T> {
 
     /// Blocking send to call outside of asynchronous contexts.
     ///
+    /// This method is intended for use cases where you are sending from
+    /// synchronous code to asynchronous code, and will work even if the
+    /// receiver is not using [`blocking_recv`] to receive the message.
+    ///
+    /// [`blocking_recv`]: fn@crate::sync::mpsc::Receiver::blocking_recv
+    ///
     /// # Panics
     ///
     /// This function panics if called within an asynchronous execution