sync: document drop behavior for channels (#5497)

Some users mentioned that the behavior of a channel when the receivers
and/or senders are dropped isn't explicitly documented.

This change adds wording to the documentation for each channel in the
sync module, explaining under which conditions messages in a channel are
dropped with respect to dropping the senders and the receivers.

Refs: #5490

tokio/src/sync/broadcast.rs

@@ -54,6 +54,10 @@
 //! all values retained by the channel, the next call to [`recv`] will return
 //! with [`RecvError::Closed`].
 //!
+//! When a [`Receiver`] handle is dropped, any messages not read by the receiver
+//! will be marked as read. If this receiver was the only one not to have read
+//! that message, the message will be dropped at this point.
+//!
 //! [`Sender`]: crate::sync::broadcast::Sender
 //! [`Sender::subscribe`]: crate::sync::broadcast::Sender::subscribe
 //! [`Receiver`]: crate::sync::broadcast::Receiver

tokio/src/sync/mpsc/mod.rs

@@ -33,7 +33,8 @@
 //!
 //! If the [`Receiver`] handle is dropped, then messages can no longer
 //! be read out of the channel. In this case, all further attempts to send will
-//! result in an error.
+//! result in an error. Additionally, all unread messages will be drained from the
+//! channel and dropped.
 //!
 //! # Clean Shutdown
 //!

tokio/src/sync/oneshot.rs

@@ -12,6 +12,10 @@
 //! Since the `send` method is not async, it can be used anywhere. This includes
 //! sending between two runtimes, and using it from non-async code.
 //!
+//! If the [`Receiver`] is closed before receiving a message which has already
+//! been sent, the message will remain in the channel until the receiver is
+//! dropped, at which point the message will be dropped immediately.
+//!
 //! # Examples
 //!
 //! ```

tokio/src/sync/watch.rs

@@ -39,6 +39,9 @@
 //! when all [`Receiver`] handles have been dropped. This indicates that there
 //! is no further interest in the values being produced and work can be stopped.
 //!
+//! The value in the channel will not be dropped until the sender and all receivers
+//! have been dropped.
+//!
 //! # Thread safety
 //!
 //! Both [`Sender`] and [`Receiver`] are thread safe. They can be moved to other