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

@@ -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");

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
     ///

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