rt: tweak spawn_blocking docs (#2955)

tokio/src/task/blocking.rs

@@ -54,31 +54,30 @@ cfg_rt_multi_thread! {
 /// Runs the provided closure on a thread where blocking is acceptable.
 ///
 /// In general, issuing a blocking call or performing a lot of compute in a
-/// future without yielding is not okay, as it may prevent the executor from
+/// future without yielding is problematic, as it may prevent the executor from
-/// driving other futures forward. This function runs the provided closure
+/// driving other futures forward. This function runs the provided closure on a
-/// on a thread dedicated to blocking operations. See the [CPU-bound tasks
+/// thread dedicated to blocking operations. See the [CPU-bound tasks and
-/// and blocking code][blocking] section for more information.
+/// blocking code][blocking] section for more information.
 ///
-/// Tokio will spawn more blocking threads when they are requested through
+/// Tokio will spawn more blocking threads when they are requested through this
-/// this function until the upper limit configured on the [`Builder`] is
+/// function until the upper limit configured on the [`Builder`] is reached.
-/// reached.  This limit is very large by default, because `spawn_blocking` is
+/// This limit is very large by default, because `spawn_blocking` is often used
-/// often used for various kinds of IO operations that cannot be performed
+/// for various kinds of IO operations that cannot be performed asynchronously.
-/// asynchronously. When you run CPU-bound code using `spawn_blocking`, you
+/// When you run CPU-bound code using `spawn_blocking`, you should keep this
-/// should keep this large upper limit in mind; to run your CPU-bound
+/// large upper limit in mind. When running many CPU-bound computations, a
-/// computations on only a few threads, you should use a separate thread
+/// semaphore or some other synchronization primitive should be used to limit
-/// pool such as [rayon] rather than configuring the number of blocking
+/// the number of computation executed in parallel. Specialized CPU-bound
-/// threads.
+/// executors, such as [rayon], may also be a good fit.
 ///
-/// This function is intended for non-async operations that eventually
+/// This function is intended for non-async operations that eventually finish on
-/// finish on their own. If you want to spawn an ordinary thread, you should
+/// their own. If you want to spawn an ordinary thread, you should use
-/// use [`thread::spawn`] instead.
+/// [`thread::spawn`] instead.
 ///
-/// Closures spawned using `spawn_blocking` cannot be cancelled. When you
+/// Closures spawned using `spawn_blocking` cannot be cancelled. When you shut
-/// shut down the executor, it will wait indefinitely for all blocking
+/// down the executor, it will wait indefinitely for all blocking operations to
-/// operations to finish. You can use [`shutdown_timeout`] to stop waiting
+/// finish. You can use [`shutdown_timeout`] to stop waiting for them after a
-/// for them after a certain timeout. Be aware that this will still not
+/// certain timeout. Be aware that this will still not cancel the tasks — they
-/// cancel the tasks — they are simply allowed to keep running after the
+/// are simply allowed to keep running after the method returns.
-/// method returns.
 ///
 /// Note that if you are using the single threaded runtime, this function will
 /// still spawn additional threads for blocking operations. The basic