Merge pull request #294 from async-rs/blocking-docs

add task::blocking docs

Author: yoshuawuyts

Diff for: src/task/block_on.rs

@@ -19,6 +19,10 @@ use kv_log_macro::trace;
 /// Calling this function is similar to [spawning] a thread and immediately [joining] it, except an
 /// asynchronous task will be spawned.
 ///
+/// See also: [`task::blocking`].
+///
+/// [`task::blocking`]: fn.blocking.html
+///
 /// [spawning]: https://doc.rust-lang.org/std/thread/fn.spawn.html
 /// [joining]: https://doc.rust-lang.org/std/thread/struct.JoinHandle.html#method.join
 ///

Diff for: src/task/mod.rs

@@ -51,7 +51,29 @@ pub(crate) mod blocking;
 
 /// Spawns a blocking task.
 ///
-/// The task will be spawned onto a thread pool specifically dedicated to blocking tasks.
+/// The task will be spawned onto a thread pool specifically dedicated to blocking tasks. This
+/// is useful to prevent long-running synchronous operations from blocking the main futures
+/// executor.
+///
+/// See also: [`task::block_on`].
+///
+/// [`task::block_on`]: fn.block_on.html
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```
+/// # fn main() { async_std::task::block_on(async {
+/// #
+/// use async_std::task;
+///
+/// task::blocking(async {
+///     println!("long-running task here");
+/// }).await;
+/// #
+/// # }) }
+/// ```
 // Once this function stabilizes we should merge `blocking::spawn` into this so
 // all code in our crate uses `task::blocking` too.
 #[cfg(any(feature = "unstable", feature = "docs"))]