diff --git a/.mailmap b/.mailmap index 40e9c003313ce..c2d3b28602bcc 100644 --- a/.mailmap +++ b/.mailmap @@ -52,7 +52,6 @@ Chris Pressey Chris Thorn Chris Thorn Clark Gaebel Clinton Ryan -Corey Farwell Corey Farwell Corey Richardson Elaine "See More" Nemo Cyryl Płotnicki Damien Schoof diff --git a/src/doc/rustdoc/src/passes.md b/src/doc/rustdoc/src/passes.md index 12054d04a7e3e..de7c10292680c 100644 --- a/src/doc/rustdoc/src/passes.md +++ b/src/doc/rustdoc/src/passes.md @@ -1,3 +1,86 @@ # Passes -Coming soon! \ No newline at end of file +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. diff --git a/src/libcore/ops/deref.rs b/src/libcore/ops/deref.rs index a2e7c44cb249f..ea8dd82087849 100644 --- a/src/libcore/ops/deref.rs +++ b/src/libcore/ops/deref.rs @@ -27,6 +27,7 @@ /// # More on `Deref` coercion /// /// If `T` implements `Deref`, 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`, 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` diff --git a/src/librustdoc/html/static/main.js b/src/librustdoc/html/static/main.js index 84ab88c4fdc08..8ec9cd8660a80 100644 --- a/src/librustdoc/html/static/main.js +++ b/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'; }); } } diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 80eb8ba93f754..3cd9cf7727c20 100644 --- a/src/libstd/thread/mod.rs +++ b/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,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()) } ) diff --git a/src/libstd/time/mod.rs b/src/libstd/time/mod.rs index 40113d164df55..e8eb4abaa40c9 100644 --- a/src/libstd/time/mod.rs +++ b/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. ///