[DOC] Improve the thread::park and thread::unpark documentation #41809

gamazeps · 2017-05-07T14:06:42Z

Part of #29378 .

Takes care of the documentation for park, park_duration and also improves the unpark example.

park should have its module documentation inlined here, and cleaned up.
park_timeout could use links to park.

Part of rust-lang#29378

- Adds an explanantion of what `park` does in the `unpark` documentation. - Adds a link to the module doc.

Part of rust-lang#29378

rust-highfive · 2017-05-07T14:06:53Z

r? @alexcrichton

(rust_highfive has picked a reviewer for you, use r? to override)

Mark-Simulacrum · 2017-05-07T14:07:37Z

r? @steveklabnik

kennytm · 2017-05-07T14:09:55Z

src/libstd/thread/mod.rs

-/// The semantics of this function are equivalent to `park()` except that the
-/// thread will be blocked for roughly no longer than `ms`. This method
-/// should not be used for precise timing due to anomalies such as
+/// The semantics of this function are equivalent to [`park()`][[park] except


Too many [ here?

kennytm · 2017-05-07T14:10:26Z

src/libstd/thread/mod.rs

-/// The semantics of this function are equivalent to `park()` except that the
-/// thread will be blocked for roughly no longer than `dur`. This method
-/// should not be used for precise timing due to anomalies such as
+/// The semantics of this function are equivalent to [`park()`][[park] except


ditto. 👍

kennytm · 2017-05-07T16:58:35Z

src/libstd/thread/mod.rs

 ///
-/// [unpark]: struct.Thread.html#method.unpark
+/// In other words, each [`Thread`] acts a bit like a spinlock that can be
+/// lockend and unlocked using `park` and `unpark`.


So much typos, the shame is strong in me.

kennytm · 2017-05-07T16:59:28Z

src/libstd/thread/mod.rs

+/// # park and unpark
+///
+/// Every thread is equipped with some basic low-level blocking support, via the
+/// [`thread::park`][`park`] function and [`thread::Thread::unpark()`][`unpark`]


I don't know if you are allowed to use the () here 😄

It is used elsewhre and I checked that they worked, so I think I am allowed to do that.
I can be removed if you want to though.

currently, the policy is to remove the () for method/function names in docs (see also #40456), though it's not a huge deal

It shall be done then :p

kennytm · 2017-05-07T17:01:24Z

src/libstd/thread/mod.rs

@@ -591,11 +604,10 @@ pub fn park() {
 /// preemption or platform differences that may not cause the maximum
 /// amount of time waited to be precisely `ms` long.
 ///
-/// See the [module documentation][thread] for more detail.
+/// See the [park documentation][park] for more detail.


The link should point to [`park`]

Indeed, missed that one.

this still needs to be fixed

Part of rust-lang#29378 - Moves the module documentation into `park`. - Add the same example as the one from `unpark` to `park`.

frewsxcv · 2017-05-07T19:36:04Z

src/libstd/thread/mod.rs

+///     .unwrap();
+///
+/// // Let some time pass for the thread to be spawned.
+/// thread::sleep(Duration::from_millis(10));


As per the failures on Travis (scroll near the bottom), you'll need to import Duration into scope here

(this has been addressed)

gamazeps · 2017-05-07T19:48:22Z

All comments are addressed (sory for the delay I'm following the French election at the same time :p)

carols10cents · 2017-05-08T13:10:12Z

Looks like one travis job failed due to network failure on checking out the PR, logged here #40474 (comment) and restarted the travis build.

steveklabnik

r=me after that link gets fixed

steveklabnik · 2017-05-09T16:29:34Z

src/libstd/thread/mod.rs

@@ -591,11 +604,10 @@ pub fn park() {
 /// preemption or platform differences that may not cause the maximum
 /// amount of time waited to be precisely `ms` long.
 ///
-/// See the [module documentation][thread] for more detail.
+/// See the [park documentation][park] for more detail.


this still needs to be fixed

steveklabnik · 2017-05-09T16:29:46Z

src/libstd/thread/mod.rs

+///     .unwrap();
+///
+/// // Let some time pass for the thread to be spawned.
+/// thread::sleep(Duration::from_millis(10));


(this has been addressed)

[Doc] improve `thread::Thread` and `thread::Builder` documentations Part of #29378 - Adds information about the stack_size when using `Builder`. This might be considered too low level, but I assume that if someone wants to create their own builder instead of using `thread::spawn` they may be interested in that info. - Updates the `thread::Thread` structure doc, mostly by explaining how to get one, the previous example was removed because it was not related to `thread::Thread`, but rather to `thread::Builder::name`. Not much is present there, mostly because this API is not often used (the only method that seems useful is `unpark`, which is documented in #41809).

frewsxcv · 2017-05-10T01:29:48Z

@bors r=steveklabnik rollup

bors · 2017-05-10T01:29:49Z

📌 Commit afe74c3 has been approved by steveklabnik

[DOC] Improve the thread::park and thread::unpark documentation Part of rust-lang#29378 . Takes care of the documentation for `park`, `park_duration` and also improves the `unpark` example. - `park should` have its module documentation inlined here, and cleaned up. - `park_timeout` could use links to `park`.

gamazeps · 2017-05-10T08:46:19Z

Link is fixed I think :)

[DOC] Improve the thread::park and thread::unpark documentation Part of rust-lang#29378 . Takes care of the documentation for `park`, `park_duration` and also improves the `unpark` example. - `park should` have its module documentation inlined here, and cleaned up. - `park_timeout` could use links to `park`.

frewsxcv · 2017-05-10T13:54:32Z

Yep, looks fixed! Just waiting to be tested and merged by our infrastructure

[DOC] Improve the thread::park and thread::unpark documentation Part of rust-lang#29378 . Takes care of the documentation for `park`, `park_duration` and also improves the `unpark` example. - `park should` have its module documentation inlined here, and cleaned up. - `park_timeout` could use links to `park`.

Rollup of 5 pull requests - Successful merges: #41531, #41536, #41809, #41854, #41886 - Failed merges:

Felix Raimundo added 4 commits May 7, 2017 13:47

Add a link to park in the park_timeout doc.

061b56b

Part of rust-lang#29378

Add link to the module doc in park_timeout.

c158962

Part of rust-lang#29378

Add park info to unpark.

d9628f9

- Adds an explanantion of what `park` does in the `unpark` documentation. - Adds a link to the module doc.

Better example for thread::unpark.

5573c47

Part of rust-lang#29378

rust-highfive assigned alexcrichton May 7, 2017

Mark-Simulacrum assigned steveklabnik and unassigned alexcrichton May 7, 2017

kennytm requested changes May 7, 2017

View reviewed changes

fix typo

c0d475a

frewsxcv added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label May 7, 2017

kennytm requested changes May 7, 2017

View reviewed changes

Inline thread::park documentation.

fa0cdaa

Part of rust-lang#29378 - Moves the module documentation into `park`. - Add the same example as the one from `unpark` to `park`.

gamazeps force-pushed the thread-docs branch from 4ad2ab2 to fa0cdaa Compare May 7, 2017 17:10

gamazeps mentioned this pull request May 7, 2017

[Doc] improve thread::Thread and thread::Builder documentations #41814

Merged

frewsxcv reviewed May 7, 2017

View reviewed changes

Fix typos in thread::park documentation.

03c9510

gamazeps force-pushed the thread-docs branch from d412f12 to 03c9510 Compare May 7, 2017 19:50

carols10cents added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 8, 2017

steveklabnik suggested changes May 9, 2017

View reviewed changes

Fix link

afe74c3

frewsxcv mentioned this pull request May 10, 2017

Rollup of 9 pull requests #41872

Closed

frewsxcv mentioned this pull request May 10, 2017

Rollup of 8 pull requests #41881

Closed

steveklabnik mentioned this pull request May 10, 2017

Rollup of 5 pull requests #41887

Merged

bors added a commit that referenced this pull request May 10, 2017

Auto merge of #41887 - steveklabnik:rollup, r=steveklabnik

978d2cf

Rollup of 5 pull requests - Successful merges: #41531, #41536, #41809, #41854, #41886 - Failed merges:

bors merged commit afe74c3 into rust-lang:master May 10, 2017

gamazeps deleted the thread-docs branch May 13, 2017 17:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC] Improve the thread::park and thread::unpark documentation #41809

[DOC] Improve the thread::park and thread::unpark documentation #41809

gamazeps commented May 7, 2017

rust-highfive commented May 7, 2017

Mark-Simulacrum commented May 7, 2017

kennytm May 7, 2017

gamazeps May 7, 2017

kennytm May 7, 2017

gamazeps May 7, 2017

kennytm May 7, 2017

gamazeps May 7, 2017

kennytm May 7, 2017

gamazeps May 7, 2017 •

edited

Loading

frewsxcv May 7, 2017

gamazeps May 7, 2017

kennytm May 7, 2017 •

edited

Loading

gamazeps May 7, 2017

steveklabnik May 9, 2017

gamazeps May 9, 2017

frewsxcv May 7, 2017

gamazeps May 7, 2017

steveklabnik May 9, 2017

gamazeps commented May 7, 2017

carols10cents commented May 8, 2017

steveklabnik left a comment

steveklabnik May 9, 2017

steveklabnik May 9, 2017

frewsxcv commented May 10, 2017

bors commented May 10, 2017

gamazeps commented May 10, 2017

frewsxcv commented May 10, 2017

[DOC] Improve the thread::park and thread::unpark documentation #41809

[DOC] Improve the thread::park and thread::unpark documentation #41809

Conversation

gamazeps commented May 7, 2017

rust-highfive commented May 7, 2017

Mark-Simulacrum commented May 7, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gamazeps May 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennytm May 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gamazeps commented May 7, 2017

carols10cents commented May 8, 2017

steveklabnik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

frewsxcv commented May 10, 2017

bors commented May 10, 2017

gamazeps commented May 10, 2017

frewsxcv commented May 10, 2017

gamazeps May 7, 2017 •

edited

Loading

kennytm May 7, 2017 •

edited

Loading