doc: remove "idiomatic choice" from queueMicrotask #23885
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Trott
approved these changes
Oct 25, 2018
jasnell
approved these changes
Oct 26, 2018
Trott
added
the
author ready
hiroppy
approved these changes
Oct 26, 2018
apapirovski
reviewed
Oct 26, 2018
doc/api/globals.md
Outdated
| @@ -122,7 +122,6 @@ The `queueMicrotask()` method queues a microtask to invoke `callback`. If | |||
| `callback` throws an exception, the [`process` object][] `'uncaughtException'` | |||
| event will be emitted. | |||
|
|
|||
| In general, `queueMicrotask` is the idiomatic choice over `process.nextTick()`. | |||
| `process.nextTick()` will always run before the microtask queue, and so | |||
There was a problem hiding this comment.
FWIW, this whole paragraph is kinda sketchy. There is nothing unexpected about the nextTick execution order. As for Node 10 it is entirely predictable and defined, with no weird edge cases. It might not be "desired" but that's up to the individual user.
There was a problem hiding this comment.
I may be wrong, but the transition from the previous paragraph to the process.nextTick() mention seems a bit abrupt and unexpected now. Maybe we can add some smooth connection? Like On the other hand..., Similar `process.nextTick()`... etc?
addaleax
approved these changes
Oct 26, 2018
trivikr
approved these changes
Oct 26, 2018
cjihrig
approved these changes
Oct 26, 2018
lpinca
approved these changes
Oct 26, 2018
mmarchini
approved these changes
Oct 26, 2018
It can't be idiomatic if it's not in general use and therefore hasn't been picked up by users. It's not even in browsers yet. "Idiomatic" use is an emergent property that comes from observed use and this feature is so new (to browsers and Node) that it can't possibly be. In general I don't think it's the place of the Node API docs to observe what emerges as idiomatic Node.js. It also can't be a recommended feature (if that was the intent of the language) because it's marked experimental. For now, it's just a feature, nothing more. Recommendations and/or observations about it being 'idiomatic' can come later.
rvagg
force-pushed
the
rvagg/queue-microtask-not-idiomatic
branch
from
d1fd048
to
999ddf4
Compare
rvagg
force-pushed
the
rvagg/queue-microtask-not-idiomatic
branch
from
999ddf4
to
a6da5fd
Compare
|
@apapirovski & @vsemozhetbyt good point on the flow into that second paragraph. I've expanded it to be a bit more helpful and the latest commit reads:
Thoughts? |
vsemozhetbyt
approved these changes
Oct 29, 2018
TimothyGu
approved these changes
Oct 29, 2018
rvagg
added a commit
that referenced
this pull request
Oct 30, 2018
It can't be idiomatic if it's not in general use and therefore hasn't been picked up by users. It's not even in browsers yet. "Idiomatic" use is an emergent property that comes from observed use and this feature is so new (to browsers and Node) that it can't possibly be. In general I don't think it's the place of the Node API docs to observe what emerges as idiomatic Node.js. It also can't be a recommended feature (if that was the intent of the language) because it's marked experimental. For now, it's just a feature, nothing more. Recommendations and/or observations about it being 'idiomatic' can come later. PR-URL: #23885 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Yuta Hiroto <hello@hiroppy.me> Reviewed-By: Matheus Marchini <mat@mmarchini.me> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
targos
pushed a commit
that referenced
this pull request
Nov 1, 2018
It can't be idiomatic if it's not in general use and therefore hasn't been picked up by users. It's not even in browsers yet. "Idiomatic" use is an emergent property that comes from observed use and this feature is so new (to browsers and Node) that it can't possibly be. In general I don't think it's the place of the Node API docs to observe what emerges as idiomatic Node.js. It also can't be a recommended feature (if that was the intent of the language) because it's marked experimental. For now, it's just a feature, nothing more. Recommendations and/or observations about it being 'idiomatic' can come later. PR-URL: #23885 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Yuta Hiroto <hello@hiroppy.me> Reviewed-By: Matheus Marchini <mat@mmarchini.me> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
This was referenced Nov 2, 2018
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
It can't be idiomatic if it's not in general use and therefore hasn't
been picked up by users. It's not even in browsers yet.
"Idiomatic" use is an emergent property that comes from observed use
and this feature is so new (to browsers and Node) that it can't
possibly be. In general I don't think it's the place of the Node API
docs to observe what emerges as idiomatic Node.js.
It also can't be a recommended feature (if that was the intent of the
language) because it's marked experimental. For now, it's just a
feature, nothing more. Recommendations and/or observations about it
being 'idiomatic' can come later.