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.

2 files changed, 14 insertions, 7 deletions

diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs
index c2217413..db53543e 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 3aafc406..cd8fbb1c 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
     ///