From 279712c290730a24bf8c36dae833de2228ca5a9c Mon Sep 17 00:00:00 2001
From: b-naber <bn263@gmx.de>
Date: Fri, 22 Jul 2022 17:47:01 +0200
Subject: [PATCH] docs

---
 tokio/src/sync/mpsc/bounded.rs | 39 ++++++++++++----------------------
 tokio/src/sync/mpsc/chan.rs    |  2 +-
 2 files changed, 15 insertions(+), 26 deletions(-)

diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs
index 5889d8d9215..6c1125c3eae 100644
--- a/tokio/src/sync/mpsc/bounded.rs
+++ b/tokio/src/sync/mpsc/bounded.rs
@@ -22,43 +22,32 @@ pub struct Sender<T> {
     chan: chan::Tx<T, Semaphore>,
 }
 
-/// A Sender that does not influence RAII semantics, i.e. if all [`Sender`]
-/// instances of a channel were dropped and only `WeakSender` instances remain,
-/// the channel is closed.
+/// If all [`Sender`] instances of a channel were dropped and only `WeakSender`
+/// instances remain, the channel is closed.
 ///
 /// In order to send messages, the `WeakSender` needs to be upgraded using
-/// [`WeakSender::upgrade`], which returns `Option<Sender>`, `None` if all
-/// `Sender`s were already dropped, otherwise `Some` (at which point it does
-/// influence RAII semantics again).
+/// [`WeakSender::upgrade`], which returns `Option<Sender>`. It returns `None`
+/// if all `Sender`s have been dropped, and otherwise it returns a `Sender`.
 ///
 /// [`Sender`]: Sender
 /// [`WeakSender::upgrade`]: WeakSender::upgrade
 ///
 /// #Examples
 ///
-/// ```rust
-/// use tokio;
+/// ```
 /// use tokio::sync::mpsc::channel;
 ///
 /// #[tokio::main]
 /// async fn main() {
-///     let (tx, mut rx) = channel(15);
-///     let _ = tx.send(1).await;
-///     let tx_weak = tx.downgrade();
-///
-///     let _ = tokio::spawn(async move {
-///         for i in 0..2 {
-///             if i == 0 {
-///                 assert_eq!(rx.recv().await.unwrap(), 1);
-///             } else if i == 1 {
-///                 // only WeakSender instance remains -> channel is dropped
-///                 assert!(rx.recv().await.is_none());
-///             }
-///         }
-///     })
-///     .await;
-///
-///     assert!(tx_weak.upgrade().is_none());
+///     let (tx, rx) = channel(15);
+///     let tx_weak = tx.clone().downgrade();
+///   
+///     // Upgrading will succeed because `tx` still exists.
+///     assert!(tx_weak.clone().upgrade().is_some());
+///   
+///     // If we drop `tx`, then it will fail.
+///     drop(tx);
+///     assert!(tx_weak.clone().upgrade().is_none());
 /// }
 ///
 /// ```
diff --git a/tokio/src/sync/mpsc/chan.rs b/tokio/src/sync/mpsc/chan.rs
index f6e9e0fab24..9ba55d898a2 100644
--- a/tokio/src/sync/mpsc/chan.rs
+++ b/tokio/src/sync/mpsc/chan.rs
@@ -142,7 +142,7 @@ impl<T, S> Tx<T, S> {
         self
     }
 
-    // Returns a boolean that indicates whether the channel is closed.
+    // Returns the upgraded channel or None if the upgrade failed.
     pub(super) fn upgrade(self) -> Option<Self> {
         let mut tx_count = self.inner.tx_count.load(Acquire);