Auto merge of #33487 - steveklabnik:rollup, r=steveklabnik

Rollup of 20 pull requests

- Successful merges: #33256, #33283, #33313, #33314, #33326, #33336, #33382, #33384, #33402, #33409, #33410, #33412, #33428, #33430, #33437, #33438, #33439, #33442, #33456, #33459
- Failed merges:

7 files changed, 222 insertions, 32 deletions

diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index ca15aa2d56c..a058337a50a 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -182,11 +182,10 @@
 //!
 //! # fn foo() -> io::Result<()> {
 //! let f = try!(File::open("foo.txt"));
-//! let mut reader = BufReader::new(f);
+//! let reader = BufReader::new(f);
 //!
 //! for line in reader.lines() {
-//!     let line = try!(line);
-//!     println!("{}", line);
+//!     println!("{}", try!(line));
 //! }
 //!
 //! # Ok(())
diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs
index adceee6d73e..45b85d600a6 100644
--- a/src/libstd/net/ip.rs
+++ b/src/libstd/net/ip.rs
@@ -89,7 +89,7 @@ impl Ipv4Addr {
 
     /// Returns true if this is a loopback address (127.0.0.0/8).
     ///
-    /// This property is defined by RFC 6890
+    /// This property is defined by RFC 6890.
     #[stable(since = "1.7.0", feature = "ip_17")]
     pub fn is_loopback(&self) -> bool {
         self.octets()[0] == 127
@@ -97,7 +97,7 @@ impl Ipv4Addr {
 
     /// Returns true if this is a private address.
     ///
-    /// The private address ranges are defined in RFC1918 and include:
+    /// The private address ranges are defined in RFC 1918 and include:
     ///
     ///  - 10.0.0.0/8
     ///  - 172.16.0.0/12
@@ -114,7 +114,7 @@ impl Ipv4Addr {
 
     /// Returns true if the address is link-local (169.254.0.0/16).
     ///
-    /// This property is defined by RFC 6890
+    /// This property is defined by RFC 6890.
     #[stable(since = "1.7.0", feature = "ip_17")]
     pub fn is_link_local(&self) -> bool {
         self.octets()[0] == 169 && self.octets()[1] == 254
@@ -140,7 +140,7 @@ impl Ipv4Addr {
     /// Returns true if this is a multicast address.
     ///
     /// Multicast addresses have a most significant octet between 224 and 239,
-    /// and is defined by RFC 5771
+    /// and is defined by RFC 5771.
     #[stable(since = "1.7.0", feature = "ip_17")]
     pub fn is_multicast(&self) -> bool {
         self.octets()[0] >= 224 && self.octets()[0] <= 239
@@ -354,7 +354,7 @@ impl Ipv6Addr {
 
     /// Returns true if this is a unique local address (IPv6).
     ///
-    /// Unique local addresses are defined in RFC4193 and have the form fc00::/7.
+    /// Unique local addresses are defined in RFC 4193 and have the form fc00::/7.
     pub fn is_unique_local(&self) -> bool {
         (self.segments()[0] & 0xfe00) == 0xfc00
     }
@@ -371,7 +371,7 @@ impl Ipv6Addr {
     }
 
     /// Returns true if this is an address reserved for documentation
-    /// This is defined to be 2001:db8::/32 in RFC RFC 3849
+    /// This is defined to be 2001:db8::/32 in RFC 3849.
     pub fn is_documentation(&self) -> bool {
         (self.segments()[0] == 0x2001) && (self.segments()[1] == 0xdb8)
     }
diff --git a/src/libstd/process.rs b/src/libstd/process.rs
index 1d2516a4c40..7a86e726b3a 100644
--- a/src/libstd/process.rs
+++ b/src/libstd/process.rs
@@ -215,12 +215,38 @@ impl Command {
     ///
     /// Builder methods are provided to change these defaults and
     /// otherwise configure the process.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("sh")
+    ///         .spawn()
+    ///         .expect("sh command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn new<S: AsRef<OsStr>>(program: S) -> Command {
         Command { inner: imp::Command::new(program.as_ref()) }
     }
 
     /// Add an argument to pass to the program.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("ls")
+    ///         .arg("-l")
+    ///         .arg("-a")
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Command {
         self.inner.arg(arg.as_ref());
@@ -228,6 +254,19 @@ impl Command {
     }
 
     /// Add multiple arguments to pass to the program.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("ls")
+    ///         .args(&["-l", "-a"])
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn args<S: AsRef<OsStr>>(&mut self, args: &[S]) -> &mut Command {
         for arg in args {
@@ -240,6 +279,19 @@ impl Command {
     ///
     /// Note that environment variable names are case-insensitive (but case-preserving) on Windows,
     /// and case-sensitive on all other platforms.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("ls")
+    ///         .env("PATH", "/bin")
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Command
         where K: AsRef<OsStr>, V: AsRef<OsStr>
@@ -249,6 +301,19 @@ impl Command {
     }
 
     /// Removes an environment variable mapping.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("ls")
+    ///         .env_remove("PATH")
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn env_remove<K: AsRef<OsStr>>(&mut self, key: K) -> &mut Command {
         self.inner.env_remove(key.as_ref());
@@ -256,6 +321,19 @@ impl Command {
     }
 
     /// Clears the entire environment map for the child process.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("ls")
+    ///         .env_clear()
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn env_clear(&mut self) -> &mut Command {
         self.inner.env_clear();
@@ -263,6 +341,19 @@ impl Command {
     }
 
     /// Sets the working directory for the child process.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("ls")
+    ///         .current_dir("/bin")
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Command {
         self.inner.cwd(dir.as_ref().as_ref());
@@ -270,6 +361,19 @@ impl Command {
     }
 
     /// Configuration for the child process's stdin handle (file descriptor 0).
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::{Command, Stdio};
+    ///
+    /// Command::new("ls")
+    ///         .stdin(Stdio::null())
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn stdin(&mut self, cfg: Stdio) -> &mut Command {
         self.inner.stdin(cfg.0);
@@ -277,6 +381,19 @@ impl Command {
     }
 
     /// Configuration for the child process's stdout handle (file descriptor 1).
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::{Command, Stdio};
+    ///
+    /// Command::new("ls")
+    ///         .stdout(Stdio::null())
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn stdout(&mut self, cfg: Stdio) -> &mut Command {
         self.inner.stdout(cfg.0);
@@ -284,6 +401,19 @@ impl Command {
     }
 
     /// Configuration for the child process's stderr handle (file descriptor 2).
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::{Command, Stdio};
+    ///
+    /// Command::new("ls")
+    ///         .stderr(Stdio::null())
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn stderr(&mut self, cfg: Stdio) -> &mut Command {
         self.inner.stderr(cfg.0);
@@ -293,6 +423,18 @@ impl Command {
     /// Executes the command as a child process, returning a handle to it.
     ///
     /// By default, stdin, stdout and stderr are inherited from the parent.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("ls")
+    ///         .spawn()
+    ///         .expect("ls command failed to start");
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn spawn(&mut self) -> io::Result<Child> {
         self.inner.spawn(imp::Stdio::Inherit, true).map(Child::from_inner)
@@ -308,8 +450,10 @@ impl Command {
     ///
     /// ```should_panic
     /// use std::process::Command;
-    /// let output = Command::new("/bin/cat").arg("file.txt").output()
-    ///     .expect("failed to execute process");
+    /// let output = Command::new("/bin/cat")
+    ///                      .arg("file.txt")
+    ///                      .output()
+    ///                      .expect("failed to execute process");
     ///
     /// println!("status: {}", output.status);
     /// println!("stdout: {}", String::from_utf8_lossy(&output.stdout));
@@ -333,8 +477,10 @@ impl Command {
     /// ```should_panic
     /// use std::process::Command;
     ///
-    /// let status = Command::new("/bin/cat").arg("file.txt").status()
-    ///     .expect("failed to execute process");
+    /// let status = Command::new("/bin/cat")
+    ///                      .arg("file.txt")
+    ///                      .status()
+    ///                      .expect("failed to execute process");
     ///
     /// println!("process exited with: {}", status);
     ///
@@ -469,12 +615,42 @@ impl fmt::Display for ExitStatus {
 impl Child {
     /// Forces the child to exit. This is equivalent to sending a
     /// SIGKILL on unix platforms.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// let mut command = Command::new("yes");
+    /// if let Ok(mut child) = command.spawn() {
+    ///     child.kill().expect("command wasn't running");
+    /// } else {
+    ///     println!("yes command didn't start");
+    /// }
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn kill(&mut self) -> io::Result<()> {
         self.handle.kill()
     }
 
     /// Returns the OS-assigned process identifier associated with this child.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// let mut command = Command::new("ls");
+    /// if let Ok(child) = command.spawn() {
+    ///     println!("Child's id is {}", child.id());
+    /// } else {
+    ///     println!("ls command didn't start");
+    /// }
+    /// ```
     #[stable(feature = "process_id", since = "1.3.0")]
     pub fn id(&self) -> u32 {
         self.handle.id()
@@ -488,6 +664,22 @@ impl Child {
     /// before waiting. This helps avoid deadlock: it ensures that the
     /// child does not block waiting for input from the parent, while
     /// the parent waits for the child to exit.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// let mut command = Command::new("ls");
+    /// if let Ok(mut child) = command.spawn() {
+    ///     child.wait().expect("command wasn't running");
+    ///     println!("Child has finished its execution!");
+    /// } else {
+    ///     println!("ls command didn't start");
+    /// }
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub fn wait(&mut self) -> io::Result<ExitStatus> {
         drop(self.stdin.take());
diff --git a/src/libstd/sync/barrier.rs b/src/libstd/sync/barrier.rs
index b543240c15a..b1267acdee6 100644
--- a/src/libstd/sync/barrier.rs
+++ b/src/libstd/sync/barrier.rs
@@ -71,7 +71,7 @@ impl Barrier {
         }
     }
 
-    /// Blocks the current thread until all threads has rendezvoused here.
+    /// Blocks the current thread until all threads have rendezvoused here.
     ///
     /// Barriers are re-usable after all threads have rendezvoused once, and can
     /// be used continuously.
diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs
index 09b1b0a939d..cfb8ee16cb0 100644
--- a/src/libstd/sync/rwlock.rs
+++ b/src/libstd/sync/rwlock.rs
@@ -38,8 +38,8 @@ use sys_common::rwlock as sys;
 ///
 /// # Poisoning
 ///
-/// RwLocks, like Mutexes, will become poisoned on panics. Note, however, that
-/// an RwLock may only be poisoned if a panic occurs while it is locked
+/// An `RwLock`, like `Mutex`, will become poisoned on a panic. Note, however,
+/// that an `RwLock` may only be poisoned if a panic occurs while it is locked
 /// exclusively (write mode). If a panic occurs in any reader, then the lock
 /// will not be poisoned.
 ///
diff --git a/src/libstd/sys/unix/process.rs b/src/libstd/sys/unix/process.rs
index 270c2096b2c..0500480add2 100644
--- a/src/libstd/sys/unix/process.rs
+++ b/src/libstd/sys/unix/process.rs
@@ -147,7 +147,7 @@ impl Command {
         let new_key = pair_to_key(key, val, &mut self.saw_nul);
         let (map, envp) = self.init_env_map();
 
-        // If `key` is already present then we we just update `envp` in place
+        // If `key` is already present then we just update `envp` in place
         // (and store the owned value), but if it's not there we override the
         // trailing NULL pointer, add a new NULL pointer, and store where we
         // were located.
diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs
index b3549dc1264..2f0dec759b3 100644
--- a/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@ -13,7 +13,8 @@
 //! ## The threading model
 //!
 //! An executing Rust program consists of a collection of native OS threads,
-//! each with their own stack and local state.
+//! each with their own stack and local state. Threads can be named, and
+//! provide some built-in support for low-level synchronization.
 //!
 //! Communication between threads can be done through
 //! [channels](../../std/sync/mpsc/index.html), Rust's message-passing
@@ -37,20 +38,6 @@
 //! convenient facilities for automatically waiting for the termination of a
 //! child thread (i.e., join).
 //!
-//! ## The `Thread` type
-//!
-//! Threads are represented via the `Thread` type, which you can
-//! get in one of two ways:
-//!
-//! * By spawning a new thread, e.g. using the `thread::spawn` function.
-//! * By requesting the current thread, using the `thread::current` function.
-//!
-//! Threads can be named, and provide some built-in support for low-level
-//! synchronization (described below).
-//!
-//! The `thread::current()` function is available even for threads not spawned
-//! by the APIs of this module.
-//!
 //! ## Spawning a thread
 //!
 //! A new thread can be spawned using the `thread::spawn` function:
@@ -99,6 +86,18 @@
 //! });
 //! ```
 //!
+//! ## The `Thread` type
+//!
+//! Threads are represented via the `Thread` type, which you can get in one of
+//! two ways:
+//!
+//! * By spawning a new thread, e.g. using the `thread::spawn` function, and
+//!   calling `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.
+//!
 //! ## Blocking support: park and unpark
 //!
 //! Every thread is equipped with some basic low-level blocking support, via the