Rollup of 6 pull requests

.mailmap

@@ -52,7 +52,6 @@ Chris Pressey <cpressey@gmail.com>
 Chris Thorn <chris@thorn.co> Chris Thorn <thorn@thoughtbot.com>
 Clark Gaebel <cg.wowus.cg@gmail.com> <cgaebel@mozilla.com>
 Clinton Ryan <clint.ryan3@gmail.com>
-Corey Farwell <coreyf+rust@rwell.org> Corey Farwell <coreyf@rwell.org>
 Corey Richardson <corey@octayn.net> Elaine "See More" Nemo <corey@octayn.net>
 Cyryl Płotnicki <cyplo@cyplo.net>
 Damien Schoof <damien.schoof@gmail.com>

src/doc/rustdoc/src/passes.md

@@ -1,3 +1,86 @@
 # Passes
 
-Coming soon!
+Rustdoc has a concept called "passes". These are transformations that
+`rustdoc` runs on your documentation before producing its final output.
+
+In addition to the passes below, check out the docs for these flags:
+
+* [`--passes`](command-line-arguments.html#--passes-add-more-rustdoc-passes)
+* [`--no-defaults`](command-line-arguments.html#--no-defaults-dont-run-default-passes)
+
+## Default passes
+
+By default, rustdoc will run some passes, namely:
+
+* `strip-hidden`
+* `strip-private`
+* `collapse-docs`
+* `unindent-comments`
+
+However, `strip-private` implies `strip-private-imports`, and so effectively,
+all passes are run by default.
+
+## `strip-hidden`
+
+This pass implements the `#[doc(hidden)]` attribute. When this pass runs, it
+checks each item, and if it is annotated with this attribute, it removes it
+from `rustdoc`'s output.
+
+Without this pass, these items will remain in the output.
+
+## `unindent-comments`
+
+When you write a doc comment like this:
+
+```rust,ignore
+/// This is a documentation comment.
+```
+
+There's a space between the `///` and that `T`. That spacing isn't intended
+to be a part of the output; it's there for humans, to help separate the doc
+comment syntax from the text of the comment. This pass is what removes that
+space.
+
+The exact rules are left under-specified so that we can fix issues that we find.
+
+Without this pass, the exact number of spaces is preserved.
+
+## `collapse-docs`
+
+With this pass, multiple `#[doc]` attributes are converted into one single
+documentation string.
+
+For example:
+
+```rust,ignore
+#[doc = "This is the first line."]
+#[doc = "This is the second line."]
+```
+
+Gets collapsed into a single doc string of
+
+```text
+This is the first line.
+This is the second line.
+```
+
+## `strip-private`
+
+This removes documentation for any non-public items, so for example:
+
+```rust,ignore
+/// These are private docs.
+struct Private;
+
+/// These are public docs.
+pub struct Public;
+```
+
+This pass removes the docs for `Private`, since they're not public.
+
+This pass implies `strip-priv-imports`.
+
+## `strip-priv-imports`
+
+This is the same as `strip-private`, but for `extern crate` and `use`
+statements instead of items.

src/libcore/ops/deref.rs

@@ -27,6 +27,7 @@
 /// # More on `Deref` coercion
 ///
 /// If `T` implements `Deref<Target = U>`, and `x` is a value of type `T`, then:
+///
 /// * In immutable contexts, `*x` on non-pointer types is equivalent to
 ///   `*Deref::deref(&x)`.
 /// * Values of type `&T` are coerced to values of type `&U`
@@ -113,6 +114,7 @@ impl<'a, T: ?Sized> Deref for &'a mut T {
 ///
 /// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
 /// then:
+///
 /// * In mutable contexts, `*x` on non-pointer types is equivalent to
 ///   `*Deref::deref(&x)`.
 /// * Values of type `&mut T` are coerced to values of type `&mut U`

src/librustdoc/html/static/main.js

@@ -1271,7 +1271,7 @@
                     e.innerHTML = labelForToggleButton(true);
                 });
                 onEach(toggle.getElementsByClassName('toggle-label'), function(e) {
-                    e.style.display = 'block';
+                    e.style.display = 'inline-block';
                 });
             }
         }

src/libstd/thread/mod.rs

@@ -112,6 +112,29 @@
 //! will want to make use of some form of **interior mutability** through the
 //! [`Cell`] or [`RefCell`] types.
 //!
+//! ## Naming threads
+//!
+//! Threads are able to have associated names for identification purposes. By default, spawned
+//! threads are unnamed. To specify a name for a thread, build the thread with [`Builder`] and pass
+//! the desired thread name to [`Builder::name`]. To retrieve the thread name from within the
+//! thread, use [`Thread::name`]. A couple examples of where the name of a thread gets used:
+//!
+//! * If a panic occurs in a named thread, the thread name will be printed in the panic message.
+//! * The thread name is provided to the OS where applicable (e.g. `pthread_setname_np` in
+//!   unix-like platforms).
+//!
+//! ## Stack size
+//!
+//! The default stack size for spawned threads is 2 MiB, though this particular stack size is
+//! subject to change in the future. There are two ways to manually specify the stack size for
+//! spawned threads:
+//!
+//! * Build the thread with [`Builder`] and pass the desired stack size to [`Builder::stack_size`].
+//! * Set the `RUST_MIN_STACK` environment variable to an integer representing the desired stack
+//!   size (in bytes). Note that setting [`Builder::stack_size`] will override this.
+//!
+//! Note that the stack size of the main thread is *not* determined by Rust.
+//!
 //! [channels]: ../../std/sync/mpsc/index.html
 //! [`Arc`]: ../../std/sync/struct.Arc.html
 //! [`spawn`]: ../../std/thread/fn.spawn.html
@@ -123,11 +146,14 @@
 //! [`Err`]: ../../std/result/enum.Result.html#variant.Err
 //! [`panic!`]: ../../std/macro.panic.html
 //! [`Builder`]: ../../std/thread/struct.Builder.html
+//! [`Builder::stack_size`]: ../../std/thread/struct.Builder.html#method.stack_size
+//! [`Builder::name`]: ../../std/thread/struct.Builder.html#method.name
 //! [`thread::current`]: ../../std/thread/fn.current.html
 //! [`thread::Result`]: ../../std/thread/type.Result.html
 //! [`Thread`]: ../../std/thread/struct.Thread.html
 //! [`park`]: ../../std/thread/fn.park.html
 //! [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark
+//! [`Thread::name`]: ../../std/thread/struct.Thread.html#method.name
 //! [`thread::park_timeout`]: ../../std/thread/fn.park_timeout.html
 //! [`Cell`]: ../cell/struct.Cell.html
 //! [`RefCell`]: ../cell/struct.RefCell.html
@@ -187,16 +213,8 @@ pub use self::local::{LocalKey, LocalKeyState, AccessError};
 ///
 /// The two configurations available are:
 ///
-/// - [`name`]: allows to give a name to the thread which is currently
-///   only used in `panic` messages.
-/// - [`stack_size`]: specifies the desired stack size. Note that this can
-///   be overridden by the OS.
-///
-/// 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 will be set.
-///
-/// If the [`name`] field is not specified, the thread will not be named.
+/// - [`name`]: specifies an [associated name for the thread][naming-threads]
+/// - [`stack_size`]: specifies the [desired stack size for the thread][stack-size]
 ///
 /// The [`spawn`] method will take ownership of the builder and create an
 /// [`io::Result`] to the thread handle with the given configuration.
@@ -228,6 +246,8 @@ pub use self::local::{LocalKey, LocalKeyState, AccessError};
 /// [`spawn`]: ../../std/thread/struct.Builder.html#method.spawn
 /// [`io::Result`]: ../../std/io/type.Result.html
 /// [`unwrap`]: ../../std/result/enum.Result.html#method.unwrap
+/// [naming-threads]: ./index.html#naming-threads
+/// [stack-size]: ./index.html#stack-size
 #[stable(feature = "rust1", since = "1.0.0")]
 #[derive(Debug)]
 pub struct Builder {
@@ -267,6 +287,9 @@ impl Builder {
     /// Names the thread-to-be. Currently the name is used for identification
     /// only in panic messages.
     ///
+    /// For more information about named threads, see
+    /// [this module-level documentation][naming-threads].
+    ///
     /// # Examples
     ///
     /// ```
@@ -281,6 +304,8 @@ impl Builder {
     ///
     /// handler.join().unwrap();
     /// ```
+    ///
+    /// [naming-threads]: ./index.html#naming-threads
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn name(mut self, name: String) -> Builder {
         self.name = Some(name);
@@ -292,13 +317,18 @@ impl Builder {
     /// The actual stack size may be greater than this value if
     /// the platform specifies minimal stack size.
     ///
+    /// For more information about the stack size for threads, see
+    /// [this module-level documentation][stack-size].
+    ///
     /// # Examples
     ///
     /// ```
     /// use std::thread;
     ///
     /// let builder = thread::Builder::new().stack_size(32 * 1024);
     /// ```
+    ///
+    /// [stack-size]: ./index.html#stack-size
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn stack_size(mut self, size: usize) -> Builder {
         self.stack_size = Some(size);
@@ -987,6 +1017,9 @@ impl Thread {
 
     /// Gets the thread's name.
     ///
+    /// For more information about named threads, see
+    /// [this module-level documentation][naming-threads].
+    ///
     /// # Examples
     ///
     /// Threads by default have no name specified:
@@ -1017,6 +1050,8 @@ impl Thread {
     ///
     /// handler.join().unwrap();
     /// ```
+    ///
+    /// [naming-threads]: ./index.html#naming-threads
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn name(&self) -> Option<&str> {
         self.cname().map(|s| unsafe { str::from_utf8_unchecked(s.to_bytes()) } )

src/libstd/time/mod.rs

@@ -33,10 +33,10 @@ pub use self::duration::Duration;
 
 mod duration;
 
-/// A measurement of a monotonically increasing clock.
+/// A measurement of a monotonically nondecreasing clock.
 /// Opaque and useful only with `Duration`.
 ///
-/// Instants are always guaranteed to be greater than any previously measured
+/// Instants are always guaranteed to be no less than any previously measured
 /// instant when created, and are often useful for tasks such as measuring
 /// benchmarks or timing how long an operation takes.
 ///