Add cautionary paragraph about noop wakers.

Based on a suggestion from @kpreid, with some further editing.

1 files changed, 8 insertions, 0 deletions

diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs
index baa8a956f8a..4d2de6be025 100644
--- a/library/core/src/task/wake.rs
+++ b/library/core/src/task/wake.rs
@@ -539,6 +539,10 @@ impl Waker {
     /// some futures, but are not expecting those futures to wake the waker or
     /// do not need to do anything specific if it happens.
     ///
+    /// More generally, using `Waker::noop()` to poll a future
+    /// means discarding the notification of when the future should be polled again.
+    /// So it should only be used when such a notification will not be needed to make progress.
+    ///
     /// If an owned `Waker` is needed, `clone()` this one.
     ///
     /// # Examples
@@ -796,6 +800,10 @@ impl LocalWaker {
     /// some futures, but are not expecting those futures to wake the waker or
     /// do not need to do anything specific if it happens.
     ///
+    /// More generally, using `LocalWaker::noop()` to poll a future
+    /// means discarding the notification of when the future should be polled again,
+    /// So it should only be used when such a notification will not be needed to make progress.
+    ///
     /// If an owned `LocalWaker` is needed, `clone()` this one.
     ///
     /// # Examples