From 09f92b5aedec6085863f570fe882915d0c2740f1 Mon Sep 17 00:00:00 2001
From: Maxime Grenu <69890511+cluster2600@users.noreply.github.com>
Date: Fri, 20 Feb 2026 09:34:11 +0100
Subject: [PATCH] sync: clarify that recv returns None once closed and no more
 messages (#7920)

The previous documentation stated:
  'As such, Receiver::poll returns Ok(Ready(None))'

This was misleading: when all Sender handles are dropped, recv does NOT
immediately return None. Buffered messages already in the channel can
still be received. Only after all senders are dropped AND the channel
has been fully drained does recv return None.

Also update the method reference from the internal Receiver::poll to the
public API: Receiver::recv and Receiver::poll_recv.

Closes #6053
---
 tokio/src/sync/mpsc/mod.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tokio/src/sync/mpsc/mod.rs b/tokio/src/sync/mpsc/mod.rs
index 3df612ca4..46363f933 100644
--- a/tokio/src/sync/mpsc/mod.rs
+++ b/tokio/src/sync/mpsc/mod.rs
@@ -29,7 +29,9 @@
 //!
 //! When all [`Sender`] handles have been dropped, it is no longer
 //! possible to send values into the channel. This is considered the termination
-//! event of the stream. As such, `Receiver::poll` returns `Ok(Ready(None))`.
+//! event of the stream. Once all senders have been dropped and any remaining
+//! buffered values have been received, `Receiver::recv` returns `None`
+//! (and `Receiver::poll_recv` returns `Poll::Ready(None)`).
 //!
 //! 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