Additional doc links and explanation of `Wake`.

This is intended to clarify:

* That `Wake` exists and can be used instead of `RawWaker`.
* How to construct a `Waker` when you are looking at `Wake`
  (which was previously only documented in the example).

2 files changed, 26 insertions, 6 deletions

diff --git a/library/alloc/src/task.rs b/library/alloc/src/task.rs
index 87db8629ad0..193c080d4bb 100644
--- a/library/alloc/src/task.rs
+++ b/library/alloc/src/task.rs
@@ -19,7 +19,7 @@ use core::task::Waker;
 /// The implementation of waking a task on an executor.
 ///
 /// This trait can be used to create a [`Waker`]. An executor can define an
-/// implementation of this trait, and use that to construct a Waker to pass
+/// implementation of this trait, and use that to construct a [`Waker`] to pass
 /// to the tasks that are executed on that executor.
 ///
 /// This trait is a memory-safe and ergonomic alternative to constructing a
@@ -28,7 +28,13 @@ use core::task::Waker;
 /// those for embedded systems) cannot use this API, which is why [`RawWaker`]
 /// exists as an alternative for those systems.
 ///
-/// [arc]: ../../std/sync/struct.Arc.html
+/// To construct a [`Waker`] from some type `W` implementing this trait,
+/// wrap it in an [`Arc<W>`](Arc) and call [`Waker::from()`][wi].
+/// It is also possible to convert to [`RawWaker`] in the same way.
+///
+/// <!-- This impl is reachable from `alloc` but rustdoc only lists it in `std`
+///      because `alloc` doesn't reexport `Waker` -->
+/// [wi]: ../../std/task/struct.Waker.html#impl-From<Arc<W,+Global>>-for-Waker
 ///
 /// # Examples
 ///
@@ -100,7 +106,7 @@ pub trait Wake {
 #[cfg(target_has_atomic = "ptr")]
 #[stable(feature = "wake_trait", since = "1.51.0")]
 impl<W: Wake + Send + Sync + 'static> From<Arc<W>> for Waker {
-    /// Use a `Wake`-able type as a `Waker`.
+    /// Use a [`Wake`]-able type as a `Waker`.
     ///
     /// No heap allocations or atomic operations are used for this conversion.
     fn from(waker: Arc<W>) -> Waker {
diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs
index 9ad71e394ea..c2c068977ef 100644
--- a/library/core/src/task/wake.rs
+++ b/library/core/src/task/wake.rs
@@ -9,10 +9,14 @@ use crate::ptr;
 /// A `RawWaker` allows the implementor of a task executor to create a [`Waker`]
 /// or a [`LocalWaker`] which provides customized wakeup behavior.
 ///
-/// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table
-///
 /// It consists of a data pointer and a [virtual function pointer table (vtable)][vtable]
 /// that customizes the behavior of the `RawWaker`.
+///
+/// `RawWaker`s are unsafe to use.
+/// Implementing the [`Wake`] trait is a safe alternative that requires memory allocation.
+///
+/// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table
+/// [`Wake`]: ../../alloc/task/trait.Wake.html
 #[derive(PartialEq, Debug)]
 #[stable(feature = "futures_api", since = "1.36.0")]
 pub struct RawWaker {
@@ -349,8 +353,12 @@ impl<'a> ContextBuilder<'a> {
 /// of `*waker = new_waker.clone()`, as the former will avoid cloning the waker
 /// unnecessarily if the two wakers [wake the same task](Self::will_wake).
 ///
+/// Constructing a `Waker` from a [`RawWaker`] is unsafe.
+/// Implementing the [`Wake`] trait is a safe alternative that requires memory allocation.
+///
 /// [`Future::poll()`]: core::future::Future::poll
 /// [`Poll::Pending`]: core::task::Poll::Pending
+/// [`Wake`]: ../../alloc/task/trait.Wake.html
 #[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/66401
 #[stable(feature = "futures_api", since = "1.36.0")]
 pub struct Waker {
@@ -432,9 +440,15 @@ impl Waker {
 
     /// Creates a new `Waker` from [`RawWaker`].
     ///
+    /// # Safety
+    ///
     /// The behavior of the returned `Waker` is undefined if the contract defined
     /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld.
-    /// Therefore this method is unsafe.
+    ///
+    /// (Authors wishing to avoid unsafe code may implement the [`Wake`] trait instead, at the
+    /// cost of a required heap allocation.)
+    ///
+    /// [`Wake`]: ../../alloc/task/trait.Wake.html
     #[inline]
     #[must_use]
     #[stable(feature = "futures_api", since = "1.36.0")]