From 602ad2e0ba41467f08052e152d5808ee6a695afe Mon Sep 17 00:00:00 2001
From: Alice Ryhl <alice@ryhl.io>
Date: Tue, 17 Mar 2020 22:59:26 +0100
Subject: [PATCH] runtime: update the documentation around Handle (#2328)

This PR was prompted by having encountered a few cases of people not noticing that Runtime::handle can be cloned, and therefore not realizing it could be moved to another thread.
---
 tokio/src/runtime/handle.rs | 16 +++++++++++-----
 tokio/src/runtime/mod.rs    |  5 +++--
 tokio/src/task/spawn.rs     |  4 ++++
 3 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs
index c22174136..db53543e8 100644
--- a/tokio/src/runtime/handle.rs
+++ b/tokio/src/runtime/handle.rs
@@ -7,7 +7,12 @@ cfg_rt_core! {
     use std::future::Future;
 }
 
-/// Handle to the runtime
+/// Handle to the runtime.
+///
+/// The handle is internally reference-counted and can be freely cloned. A handle can be
+/// obtained using the [`Runtime::handle`] method.
+///
+/// [`Runtime::handle`]: crate::runtime::Runtime::handle()
 #[derive(Debug, Clone)]
 pub struct Handle {
     pub(super) spawner: Spawner,
@@ -26,7 +31,7 @@ pub struct Handle {
 }
 
 impl Handle {
-    /// Enter the runtime context
+    /// Enter the runtime context.
     pub fn enter<F, R>(&self, f: F) -> R
     where
         F: FnOnce() -> R,
@@ -38,20 +43,21 @@ impl Handle {
     ///
     /// # Panic
     ///
-    /// A Runtime must have been started or this will panic
+    /// This will panic if called outside the context of a Tokio runtime.
     ///
     /// # Examples
     ///
-    /// This allows for the current handle to be gotten when running in a `#`
+    /// This can be used to obtain the handle of the surrounding runtime from an async
+    /// block or function running on that runtime.
     ///
     /// ```
     /// # use tokio::runtime::Runtime;
-    ///
     /// # fn dox() {
     /// # let rt = Runtime::new().unwrap();
     /// # rt.spawn(async {
     /// use tokio::runtime::Handle;
     ///
+    /// // Inside an async block or function.
     /// let handle = Handle::current();
     /// handle.spawn(async {
     ///     println!("now running in the existing Runtime");
diff --git a/tokio/src/runtime/mod.rs b/tokio/src/runtime/mod.rs
index 3aafc4060..cd8fbb1c3 100644
--- a/tokio/src/runtime/mod.rs
+++ b/tokio/src/runtime/mod.rs
@@ -419,7 +419,7 @@ impl Runtime {
         })
     }
 
-    /// Enter the runtime context
+    /// Enter the runtime context.
     pub fn enter<F, R>(&self, f: F) -> R
     where
         F: FnOnce() -> R,
@@ -429,7 +429,8 @@ impl Runtime {
 
     /// Return a handle to the runtime's spawner.
     ///
-    /// The returned handle can be used to spawn tasks that run on this runtime.
+    /// The returned handle can be used to spawn tasks that run on this runtime, and can
+    /// be cloned to allow moving the `Handle` to other threads.
     ///
     /// # Examples
     ///
diff --git a/tokio/src/task/spawn.rs b/tokio/src/task/spawn.rs
index 4e19f5592..fa5ff13b0 100644
--- a/tokio/src/task/spawn.rs
+++ b/tokio/src/task/spawn.rs
@@ -16,6 +16,10 @@ doc_rt_core! {
     /// When a runtime is shutdown, all outstanding tasks are dropped,
     /// regardless of the lifecycle of that task.
     ///
+    /// This function must be called from the context of a Tokio runtime. Tasks running on
+    /// the Tokio runtime are always inside its context, but you can also enter the context
+    /// using the [`Handle::enter`](crate::runtime::Handle::enter()) method.
+    ///
     /// # Examples
     ///
     /// In this example, a server is started and `spawn` is used to start a new task