Yield now docs (#2129)

* add subsections for the blocking and yielding examples in task mod

* flesh out yield_now rustdoc

* add a must_use for yield_now

2 files changed, 23 insertions, 6 deletions

diff --git a/tokio/src/task/mod.rs b/tokio/src/task/mod.rs
index efeb5f0e..073215e6 100644
--- a/tokio/src/task/mod.rs
+++ b/tokio/src/task/mod.rs
@@ -122,6 +122,8 @@
 //! Instead, Tokio provides two APIs for running blocking operations in an
 //! asynchronous context: [`task::spawn_blocking`] and [`task::block_in_place`].
 //!
+//! #### spawn_blocking
+//!
 //! The `task::spawn_blocking` function is similar to the `task::spawn` function
 //! discussed in the previous section, but rather than spawning an
 //! _non-blocking_ future on the Tokio runtime, it instead spawns a
@@ -155,6 +157,8 @@
 //! # }
 //! ```
 //!
+//! #### block_in_place
+//!
 //! When using the [threaded runtime][rt-threaded], the [`task::block_in_place`]
 //! function is also available. Like `task::spawn_blocking`, this function
 //! allows running a blocking operation from an asynchronous context. Unlike
@@ -178,11 +182,14 @@
 //! # }
 //! ```
 //!
-//! In addition, this module also provides a [`task::yield_now`] async function
-//! that is analogous to the standard library's [`thread::yield_now`]. Calling and
-//! `await`ing this function will cause the current task to yield to the Tokio
-//! runtime's scheduler, allowing another task to be scheduled. Eventually, the
-//! yielding task will be polled again, allowing it to execute. For example:
+//! #### yield_now
+//!
+//! In addition, this module provides a [`task::yield_now`] async function
+//! that is analogous to the standard library's [`thread::yield_now`]. Calling
+//! and `await`ing this function will cause the current task to yield to the
+//! Tokio runtime's scheduler, allowing other tasks to be
+//! scheduled. Eventually, the yielding task will be polled again, allowing it
+//! to execute. For example:
 //!
 //! ```rust
 //! use tokio::task;
diff --git a/tokio/src/task/yield_now.rs b/tokio/src/task/yield_now.rs
index d6d94665..e837947f 100644
--- a/tokio/src/task/yield_now.rs
+++ b/tokio/src/task/yield_now.rs
@@ -3,7 +3,17 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 
 doc_rt_core! {
-    /// Yield execution back to the Tokio runtime.
+    /// Return a `Future` that can be `await`-ed to yield execution back to the
+    /// Tokio runtime.
+    ///
+    /// A task yields by awaiting the returned `Future`, and may resume when
+    /// that future completes (with no output.) The current task will be
+    /// re-added as a pending task at the _back_ of the pending queue. Any
+    /// other pending tasks will be scheduled. No other waking is required for
+    /// the task to continue.
+    ///
+    /// See also the usage example in the [task module](index.html#yield_now).
+    #[must_use = "yield_now does nothing unless polled/`await`-ed"]
     pub async fn yield_now() {
         /// Yield implementation
         struct YieldNow {