Skip to content

Commit

Permalink
Auto merge of #43872 - frewsxcv:rollup, r=frewsxcv
Browse files Browse the repository at this point in the history
Rollup of 6 pull requests

- Successful merges: #43756, #43790, #43846, #43848, #43862, #43868
- Failed merges:
  • Loading branch information
bors committed Aug 15, 2017
2 parents 56fe3b2 + 1259db2 commit df80627
Show file tree
Hide file tree
Showing 6 changed files with 134 additions and 15 deletions.
1 change: 0 additions & 1 deletion .mailmap
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,6 @@ Chris Pressey <[email protected]>
Chris Thorn <[email protected]> Chris Thorn <[email protected]>
Clark Gaebel <[email protected]> <[email protected]>
Clinton Ryan <[email protected]>
Corey Farwell <[email protected]> Corey Farwell <[email protected]>
Corey Richardson <[email protected]> Elaine "See More" Nemo <[email protected]>
Cyryl Płotnicki <[email protected]>
Damien Schoof <[email protected]>
Expand Down
85 changes: 84 additions & 1 deletion src/doc/rustdoc/src/passes.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 2 additions & 0 deletions src/libcore/ops/deref.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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`
Expand Down
2 changes: 1 addition & 1 deletion src/librustdoc/html/static/main.js
Original file line number Diff line number Diff line change
Expand Up @@ -1271,7 +1271,7 @@
e.innerHTML = labelForToggleButton(true);
});
onEach(toggle.getElementsByClassName('toggle-label'), function(e) {
e.style.display = 'block';
e.style.display = 'inline-block';
});
}
}
Expand Down
55 changes: 45 additions & 10 deletions src/libstd/thread/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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
///
/// ```
Expand All @@ -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);
Expand All @@ -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);
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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()) } )
Expand Down
4 changes: 2 additions & 2 deletions src/libstd/time/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand Down

0 comments on commit df80627

Please sign in to comment.