Auto merge of #43872 - frewsxcv:rollup, r=frewsxcv
Rollup of 6 pull requests - Successful merges: #43756, #43790, #43846, #43848, #43862, #43868 - Failed merges:
This commit is contained in:
commit
df806275c7
6 changed files with 134 additions and 15 deletions
1
.mailmap
1
.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>
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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`
|
||||
|
|
|
@ -1271,7 +1271,7 @@
|
|||
e.innerHTML = labelForToggleButton(true);
|
||||
});
|
||||
onEach(toggle.getElementsByClassName('toggle-label'), function(e) {
|
||||
e.style.display = 'block';
|
||||
e.style.display = 'inline-block';
|
||||
});
|
||||
}
|
||||
}
|
||||
|
|
|
@ -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,6 +317,9 @@ 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
|
||||
///
|
||||
/// ```
|
||||
|
@ -299,6 +327,8 @@ impl Builder {
|
|||
///
|
||||
/// 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()) } )
|
||||
|
|
|
@ -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.
|
||||
///
|
||||
|
|
Loading…
Reference in a new issue