Enhance documentation of tokio::task::block_in_place (#2155)

tokio/src/runtime/thread_pool/worker.rs

@@ -26,7 +26,9 @@ cfg_blocking! {
         ON_BLOCK.with(|ob| {
             let allow_blocking = ob
                 .get()
-                .expect("can only call blocking when on Tokio runtime");
+                // `block_in_place` can only be called from a spawned task when
+                // working with the threaded scheduler.
+                .expect("can call blocking only when running in a spawned task");
 
             // This is safe, because ON_BLOCK was set from an &mut dyn FnMut in the worker that wraps
             // the worker's operation, and is unset just prior to when the FnMut is dropped.

tokio/src/task/blocking.rs

@@ -10,6 +10,12 @@ cfg_rt_threaded! {
     /// (possibly new) thread, and only then poll the task. Note that this requires
     /// additional synchronization.
     ///
+    /// # Note
+    ///
+    /// This function can only be called from a spawned task when working with
+    /// the [threaded scheduler](https://docs.rs/tokio/0.2.10/tokio/runtime/index.html#threaded-scheduler).
+    /// Consider using [tokio::task::spawn_blocking](https://docs.rs/tokio/0.2.10/tokio/task/fn.spawn_blocking.html).
+    ///
     /// # Examples
     ///
     /// ```