Rollup merge of #128064 - ijackson:noop-waker-doc, r=workingjubilee · patricklam/verify-rust-std@9704e2d (original) (raw)

Original file line number Diff line number Diff line change
@@ -530,10 +530,18 @@ impl Waker {
530 530
531 531 /// Returns a reference to a `Waker` that does nothing when used.
532 532 ///
533 + // Note! Much of the documentation for this method is duplicated
534 +// in the docs for `LocalWaker::noop`.
535 +// If you edit it, consider editing the other copy too.
536 +//
533 537 /// This is mostly useful for writing tests that need a [`Context`] to poll
534 538 /// some futures, but are not expecting those futures to wake the waker or
535 539 /// do not need to do anything specific if it happens.
536 540 ///
541 + /// More generally, using `Waker::noop()` to poll a future
542 + /// means discarding the notification of when the future should be polled again.
543 + /// So it should only be used when such a notification will not be needed to make progress.
544 + ///
537 545 /// If an owned `Waker` is needed, `clone()` this one.
538 546 ///
539 547 /// # Examples
@@ -783,12 +791,22 @@ impl LocalWaker {
783 791 Self { waker }
784 792 }
785 793
786 -/// Creates a new `LocalWaker` that does nothing when `wake` is called.
794 +/// Returns a reference to a `LocalWaker` that does nothing when used.
787 795 ///
796 + // Note! Much of the documentation for this method is duplicated
797 +// in the docs for `Waker::noop`.
798 +// If you edit it, consider editing the other copy too.
799 +//
788 800 /// This is mostly useful for writing tests that need a [`Context`] to poll
789 801 /// some futures, but are not expecting those futures to wake the waker or
790 802 /// do not need to do anything specific if it happens.
791 803 ///
804 + /// More generally, using `LocalWaker::noop()` to poll a future
805 + /// means discarding the notification of when the future should be polled again,
806 + /// So it should only be used when such a notification will not be needed to make progress.
807 + ///
808 + /// If an owned `LocalWaker` is needed, `clone()` this one.
809 + ///
792 810 /// # Examples
793 811 ///
794 812 /// ```