From ddb9e50b45b9762e09d341cce8547055cbee4840 Mon Sep 17 00:00:00 2001
From: Felix Raimundo <felix.raimundo@tweag.io>
Date: Sun, 7 May 2017 18:42:36 +0200
Subject: [PATCH 1/3] Add stack size doc to `thread::spawn`.

Part of #29378
---
 src/libstd/thread/mod.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs
index 4cbcfdbc2d7f6..2f7a17af77989 100644
--- a/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@ -244,6 +244,11 @@ impl Builder {
     /// Generates the base configuration for spawning a thread, from which
     /// configuration methods can be chained.
     ///
+    /// If the [`stack_size`][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 @@ impl Builder {
     ///
     /// 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 {

From c9e5eab6ff54fa4c24ab79894c4415615195db7c Mon Sep 17 00:00:00 2001
From: Felix Raimundo <felix.raimundo@tweag.io>
Date: Sun, 7 May 2017 19:26:32 +0200
Subject: [PATCH 2/3] Update the `thread::Thread` documentation.

- Copied the module documentation to `Thread`.
- Removed the example because it did not use any method of Thread.
---
 src/libstd/thread/mod.rs | 36 ++++++++++++------------------------
 1 file changed, 12 insertions(+), 24 deletions(-)

diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs
index 2f7a17af77989..d4f6c6c67c542 100644
--- a/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@ -721,33 +721,21 @@ struct Inner {
 
 #[derive(Clone)]
 #[stable(feature = "rust1", since = "1.0.0")]
-/// A handle to a thread.
+/// Threads are represented via the `Thread` type, which you can get in one of
+/// two ways:
 ///
-/// 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.
+/// * 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.
 ///
-/// # Examples
+/// 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
 

From 323a774c2f64619623c45aec068cf6c1c905d314 Mon Sep 17 00:00:00 2001
From: Felix Raimundo <felix.raimundo@tweag.io>
Date: Tue, 9 May 2017 16:52:26 +0200
Subject: [PATCH 3/3] Address review comments

---
 src/libstd/thread/mod.rs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs
index d4f6c6c67c542..9fc1def99b1ee 100644
--- a/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@ -244,7 +244,7 @@ impl Builder {
     /// Generates the base configuration for spawning a thread, from which
     /// configuration methods can be chained.
     ///
-    /// If the [`stack_size`][stack_size] field is not specified, the stack size
+    /// 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).
@@ -265,7 +265,7 @@ impl Builder {
     /// handler.join().unwrap();
     /// ```
     ///
-    /// [stack_size]: ../../std/thread/struct.Builder.html#method.stack_size
+    /// [`stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn new() -> Builder {
         Builder {
@@ -721,6 +721,8 @@ struct Inner {
 
 #[derive(Clone)]
 #[stable(feature = "rust1", since = "1.0.0")]
+/// A handle to a thread.
+///
 /// Threads are represented via the `Thread` type, which you can get in one of
 /// two ways:
 ///