Auto merge of #41814 - gamazeps:thread-struct-doc, r=steveklabnik

[Doc] improve `thread::Thread` and `thread::Builder` documentations

Part of #29378

- Adds information about the stack_size when using `Builder`. This might be considered too low level, but I assume that if someone wants to create their own builder instead of using `thread::spawn` they may be interested in that info.
- Updates the `thread::Thread` structure doc, mostly by explaining how to get one, the previous example was removed because it was not related to `thread::Thread`, but rather to `thread::Builder::name`.
  Not much is present there, mostly because this API is not often used (the only method that seems useful is `unpark`, which is documented in #41809).

diff --combined src/libstd/thread/mod.rs
index 04cd28df4459d09d7dd5389e56e4bc488a47565f,9fc1def99b1ee66637dd69d31f250010826258dd..1bb0d9f3babfd1dd1ca60f8987ea19ccadffcd47
--- 1/src/libstd/thread/mod.rs
--- 2/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@@ -244,6 -244,11 +244,11 @@@ impl Builder 
      /// Generates the base configuration for spawning a thread, from which
      /// configuration methods can be chained.
      ///
+     /// If the [`stack_size`] field is not specified, the stack size
+     /// will be the `RUST_MIN_STACK` environment variable, if it is
+     /// not specified either, a sensible default size will be set (2MB as
+     /// of the writting of this doc).
+     ///
      /// # Examples
      ///
      /// ```
@@@ -259,6 -264,8 +264,8 @@@
      ///
      /// handler.join().unwrap();
      /// ```
+     ///
+     /// [`stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size
      #[stable(feature = "rust1", since = "1.0.0")]
      pub fn new() -> Builder {
          Builder {
@@@ -458,16 -465,6 +465,16 @@@ pub fn yield_now() 
  
  /// Determines whether the current thread is unwinding because of panic.
  ///
 +/// A common use of this feature is to poison shared resources when writing
 +/// unsafe code, by checking `panicking` when the `drop` is called.
 +///
 +/// This is usually not needed when writing safe code, as [`Mutex`es][Mutex]
 +/// already poison themselves when a thread panics while holding the lock.
 +///
 +/// This can also be used in multithreaded applications, in order to send a
 +/// message to other threads warning that a thread has panicked (e.g. for
 +/// monitoring purposes).
 +///
  /// # Examples
  ///
  /// ```should_panic
@@@ -496,8 -493,6 +503,8 @@@
  ///     panic!()
  /// }
  /// ```
 +///
 +/// [Mutex]: ../../std/sync/struct.Mutex.html
  #[inline]
  #[stable(feature = "rust1", since = "1.0.0")]
  pub fn panicking() -> bool {
@@@ -728,31 -723,21 +735,21 @@@ struct Inner 
  #[stable(feature = "rust1", since = "1.0.0")]
  /// A handle to a thread.
  ///
- /// You can use it to identify a thread (by name, for example). Most of the
- /// time, there is no need to directly create a `Thread` struct using the
- /// constructor, instead you should use a function like `spawn` to create
- /// new threads, see the docs of [`Builder`] and [`spawn`] for more.
+ /// Threads are represented via the `Thread` type, which you can get in one of
+ /// two ways:
  ///
- /// # Examples
+ /// * By spawning a new thread, e.g. using the [`thread::spawn`][`spawn`]
+ ///   function, and calling [`thread`][`JoinHandle::thread`] on the
+ ///   [`JoinHandle`].
+ /// * By requesting the current thread, using the [`thread::current`] function.
+ ///
+ /// The [`thread::current`] function is available even for threads not spawned
+ /// by the APIs of this module.
+ ///
+ /// There is usualy no need to create a `Thread` struct yourself, one
+ /// should instead use a function like `spawn` to create new threads, see the
+ /// docs of [`Builder`] and [`spawn`] for more details.
  ///
- /// ```no_run
- /// # // Note that this example isn't executed by default because it causes
- /// # // deadlocks on Windows unfortunately (see #25824)
- /// use std::thread::Builder;
- ///
- /// for i in 0..5 {
- ///     let thread_name = format!("thread_{}", i);
- ///     Builder::new()
- ///         .name(thread_name) // Now you can identify which thread panicked
- ///                            // thanks to the handle's name
- ///         .spawn(move || {
- ///             if i == 3 {
- ///                  panic!("I'm scared!!!");
- ///             }
- ///         })
- ///         .unwrap();
- /// }
- /// ```
  /// [`Builder`]: ../../std/thread/struct.Builder.html
  /// [`spawn`]: ../../std/thread/fn.spawn.html