review: reference is_terminated() in documentation

NB: this commit means that this branch (tokio-rs#7153) is dependent upon
interfaces proposed in (tokio-rs#7152).

pr tokio-rs#7152 proposes a `is_terminated()` method for the oneshot channel's
receiver. that is the proper method to use to check whether or not it is
safe to poll a oneshot receiver as a future.

this commit adds a note cross-referencing this method to the
documentation of `is_empty()`, to help mitigate misuse. this method only
reports whether a value is currently waiting in the channel; a channel
that has already received and yielded a value to its receiver is also
empty, but would panic when polled.

Signed-off-by: katelyn martin <[email protected]>

Author: cratelyn

tokio/src/sync/oneshot.rs

@@ -993,8 +993,14 @@ impl<T> Receiver<T> {
     ///
     /// This method returns `true` if the channel has no messages.
     ///
+    /// It is not necessarily safe to poll an empty receiver, which may have
+    /// already yielded a value. Use [`is_terminated()`][Self::is_terminated]
+    /// to check whether or not a receiver can be safely polled, instead.
+    ///
     /// # Examples
     ///
+    /// Sending a value.
+    ///
     /// ```
     /// use tokio::sync::oneshot;
     ///
@@ -1010,6 +1016,42 @@ impl<T> Receiver<T> {
     ///     assert!(rx.is_empty());
     /// }
     /// ```
+    ///
+    /// Dropping the sender.
+    ///
+    /// ```
+    /// use tokio::sync::oneshot;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let (tx, mut rx) = oneshot::channel::<()>();
+    ///
+    ///     // A channel is empty if the sender is dropped.
+    ///     drop(tx);
+    ///     assert!(rx.is_empty());
+    ///
+    ///     // A closed channel still yields an error, however.
+    ///     (&mut rx).await.expect_err("should yield an error");
+    ///     assert!(rx.is_empty());
+    /// }
+    /// ```
+    ///
+    /// Terminated channels are empty.
+    ///
+    /// ```should_panic
+    /// use tokio::sync::oneshot;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let (tx, mut rx) = oneshot::channel();
+    ///     tx.send(0).unwrap();
+    ///     let _ = (&mut rx).await;
+    ///
+    ///     // NB: an empty channel is not necessarily safe to poll!
+    ///     assert!(rx.is_empty());
+    ///     let _ = (&mut rx).await;
+    /// }
+    /// ```
     pub fn is_empty(&self) -> bool {
         let Some(inner) = self.inner.as_ref() else {
             // The channel has already terminated.