-
-
Notifications
You must be signed in to change notification settings - Fork 34k
doc: reorganize docs of module hooks and mark sync hooks as release candidate #60960
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
|
Review requested:
|
3154919 to
b38dcae
Compare
GeoffreyBooth
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestions. Thank you for doing this.
2944f29 to
e33e818
Compare
|
Rebased to resolve the conflicts and addressed reviews. PTAL, thanks @GeoffreyBooth |
e33e818 to
03bcdbe
Compare
This reorganizes the documentation of module customization hooks to promote the synchronous variant as it has fewer caveats. Previously the documentation was organized as follows: To do something: 1. For asynchronous hooks, do this, which may have these caveats 2. For synchronous hooks, do this, which does not have the caveats To do something else: 1. For asynchronous hooks, do this, which may have these caveats 2. For synchronous hooks, do this, which does not have the caveats It's now organized as follows: Synchronous hooks: To do something, do this. To do something else, do this. (No mention that it doesn't have caveats, because users are not supposed to burden themselves with caveats in the other API that they do not use). Asynchronous hooks: They have these caveats, if they are too complex to deal with, consider use the synchronous variant. To do something, do this, which may have these caveats. To do something, do this, which may have these caveats.
03bcdbe to
6ae5d4f
Compare
| #### Caveats of asynchronous customization hooks | ||
| The asynchronous customization hooks have many caveats and the it is uncertain if their |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| The asynchronous customization hooks have many caveats and the it is uncertain if their | |
| The asynchronous customization hooks have many caveats and it is uncertain if their |
| are registered. | ||
| ##### Registering hooks before application code runs programmatically | ||
| Alternatively, `registerHooks()` can be called from the entry point. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Alternatively, `registerHooks()` can be called from the entry point. | |
| Alternatively, `registerHooks()` can be called from the entry point. |
| ``` | ||
| In this example, the registered hooks will form chains. These chains run | ||
| last-in, first out (LIFO). If both `hook1` and `hook2` define a `resolve` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| last-in, first out (LIFO). If both `hook1` and `hook2` define a `resolve` | |
| last-in, first-out (LIFO). If both `hook1` and `hook2` define a `resolve` |
| <!-- lint disable prohibited-strings remark-lint--> | ||
| Node.js' default ← `hook1.resolve` ← `hook2.resolve` | ||
| <!--lint enable prohibited-strings--> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <!-- lint disable prohibited-strings remark-lint--> | |
| Node.js' default ← `hook1.resolve` ← `hook2.resolve` | |
| <!--lint enable prohibited-strings--> | |
| Node.js default `resolve` ← `hook1.resolve` ← `hook2.resolve` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And the other similar case later on.
doc: mark sync module hooks as release candidate
doc: reorganize docs of module customization hooks
This reorganizes the documentation of module customization hooks
to promote the synchronous variant as it has fewer caveats.
Previously the documentation was organized as follows:
To do something:
To do something else:
It's now organized as follows:
Synchronous hooks:
(No mention that it doesn't have caveats, because users are not supposed
to burden themselves with caveats in the other API that they do not
use).
Asynchronous hooks:
They have these caveats, if they are too complex to deal with, consider
use the synchronous variant.
Refs: #56241