From c9814fa4850eb995019236d71f794cd8dc7c4ab0 Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Tue, 8 Aug 2017 21:37:37 -0700 Subject: [PATCH 1/9] Instant is monotonically nondecreasing We don't want to guarantee that `Instant::now() != Instant::now()` is always true since that depends on the speed of the processor and the resolution of the clock. --- src/libstd/time/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/time/mod.rs b/src/libstd/time/mod.rs index 40113d164df55..839d2188f3d0b 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 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. /// From 97d046a7278c7019a5f9ff1a0c2e30324ff0346a Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Wed, 9 Aug 2017 09:28:18 -0700 Subject: [PATCH 2/9] Fix grammar --- src/libstd/time/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/time/mod.rs b/src/libstd/time/mod.rs index 839d2188f3d0b..e8eb4abaa40c9 100644 --- a/src/libstd/time/mod.rs +++ b/src/libstd/time/mod.rs @@ -36,7 +36,7 @@ mod duration; /// A measurement of a monotonically nondecreasing clock. /// Opaque and useful only with `Duration`. /// -/// Instants are always guaranteed to no less 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. /// From 5d036cc8a6f0462b437cc261b1dae2240ff9e716 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 13 Aug 2017 11:29:28 -0400 Subject: [PATCH 3/9] Remove my mailmap entry. --- .mailmap | 1 - 1 file changed, 1 deletion(-) diff --git a/.mailmap b/.mailmap index 4b4f343d15a9d..78e6aa3f2e4a2 100644 --- a/.mailmap +++ b/.mailmap @@ -51,7 +51,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 From 150713ce9fa2e64ef8385b9f143aa46edd5d8bf4 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 13 Aug 2017 12:16:42 -0400 Subject: [PATCH 4/9] Rewrite docs for stack size/thread names for spawned threads. * Moves docs about stack size and thread naming from `Builder` to the `std::thread` module * Adds more links to the new module-level documentation * Mentions the 2 MiB stack size default, but indicate it's subject to change Fixes https://github.com/rust-lang/rust/issues/43805. --- src/libstd/thread/mod.rs | 51 ++++++++++++++++++++++++++++++++-------- 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 80eb8ba93f754..2668047b8121c 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -112,6 +112,25 @@ //! 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. For example, the thread +//! name is used in panic messages. 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`]. +//! +//! ## 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 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 +142,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 +209,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 +242,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 +283,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 +300,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 +313,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 +323,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 +1013,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 +1046,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()) } ) From 10bd80d79b006b1a81a66e1a10e333eaa38b068c Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 13 Aug 2017 16:23:13 -0400 Subject: [PATCH 5/9] Indicate thread names get passed to the OS. --- src/libstd/thread/mod.rs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 2668047b8121c..13965478aeea1 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -114,10 +114,14 @@ //! //! ## Naming threads //! -//! Threads are able to have associated names for identification purposes. For example, the thread -//! name is used in panic messages. 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`]. +//! 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 //! From 1f9d032b389d153dc2360207c454640eaef3b469 Mon Sep 17 00:00:00 2001 From: QuietMisdreavus Date: Mon, 14 Aug 2017 10:54:24 -0500 Subject: [PATCH 6/9] rustdoc: put auto-hidden docblock labels in line with the toggle --- src/librustdoc/html/static/main.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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'; }); } } From 659460191d47c81a2334bfee189ce022bd3f445b Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Mon, 14 Aug 2017 15:03:31 -0400 Subject: [PATCH 7/9] Indicate which stack size option has precedence. --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 13965478aeea1..3cd9cf7727c20 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -131,7 +131,7 @@ //! //! * 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). +//! 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. //! From 7a5ee171c34775f7155869bd16bbe38c524a555e Mon Sep 17 00:00:00 2001 From: steveklabnik Date: Thu, 10 Aug 2017 16:57:50 -0400 Subject: [PATCH 8/9] Write the "passes" chapter of the rustdoc book cc #42322 --- src/doc/rustdoc/src/passes.md | 85 ++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) 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. From 879107f1a8e4d6546370a9d6568b705d6005a420 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Mon, 14 Aug 2017 22:12:33 +0200 Subject: [PATCH 9/9] Add missing newline in Deref docs to fix rendering Fixes #43866. --- src/libcore/ops/deref.rs | 2 ++ 1 file changed, 2 insertions(+) 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`