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

1 files changed, 11 insertions, 1 deletions

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 {