Auto merge of #33665 - golddranks:thread-park-add-big-picture-explanation, r=aturon

Added a big-picture explanation for thread::park() & co.

As I said in https://www.reddit.com/r/rust/comments/4ihvv1/hey_rust_programmers_got_a_question_ask_here/d372s4i, the current explanation of the `park()` and `unpark()` is a bit unclear. It says that they're used for blocking, but then it goes on explaining the semantics in detail, leaving the bigger picture a bit unclear.

I added a short high-level explanation that explains how the functions are used. I also exposed the full paths (`thread::park()` and `thread::Thread::unpark()`), because `unpark()`, being a method, is not directly visible at the module level.

1 files changed, 3 insertions, 1 deletions

diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs
index 99e6ba8c770..dc26370590c 100644
--- a/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@ -101,7 +101,9 @@
 //! ## Blocking support: park and unpark
 //!
 //! Every thread is equipped with some basic low-level blocking support, via the
-//! `park` and `unpark` functions.
+//! `thread::park()` function and `thread::Thread::unpark()` method. `park()`
+//! blocks the current thread, which can then be resumed from another thread by
+//! calling the `unpark()` method on the blocked thread's handle.
 //!
 //! Conceptually, each `Thread` handle has an associated token, which is
 //! initially not present: