1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: remove **Note:** tags

Browse Source 
Remove the various **Note:** prefixes throughout the docs.

PR-URL: https://github.com/nodejs/node/pull/18592
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
This commit is contained in:
James M Snell 2018-02-05 21:55:16 -08:00 committed by Anatoli Papirovski
parent 809af1fe8a
commit d3569b623c
No known key found for this signature in database
GPG Key ID: 614E2E1ABEB4B2C0
32 changed files with 493 additions and 522 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/addons.md
View File

@ -115,7 +115,7 @@ specifically to compile Node.js Addons.
}
```
*Note*: A version of the `node-gyp` utility is bundled and distributed with
A version of the `node-gyp` utility is bundled and distributed with
Node.js as part of `npm`. This version is not made directly available for
developers to use and is intended only to support the ability to use the
`npm install` command to compile and install Addons. Developers who wish to

12
doc/api/async_hooks.md
View File

@ -306,8 +306,8 @@ set to the `asyncId` of a parent Promise, if there is one, and `undefined`
otherwise. For example, in the case of `b = a.then(handler)`, `a` is considered
a parent Promise of `b`.
*Note*: In some cases the resource object is reused for performance reasons,
it is thus not safe to use it as a key in a `WeakMap` or add properties to it.
In some cases the resource object is reused for performance reasons, it is
thus not safe to use it as a key in a `WeakMap` or add properties to it.
###### Asynchronous context example
@ -377,9 +377,9 @@ destroy: 9
destroy: 5
```
*Note*: As illustrated in the example, `executionAsyncId()` and `execution`
each specify the value of the current execution context; which is delineated by
calls to `before` and `after`.
As illustrated in the example, `executionAsyncId()` and `execution` each specify
the value of the current execution context; which is delineated by calls to
`before` and `after`.
Only using `execution` to graph resource allocation results in the following:
@ -599,7 +599,7 @@ own resources.
The `init` hook will trigger when an `AsyncResource` is instantiated.
*Note*: `before` and `after` calls must be unwound in the same order that they
The `before` and `after` calls must be unwound in the same order that they
are called. Otherwise, an unrecoverable exception will occur and the process
will abort.

18
doc/api/buffer.md
View File

@ -195,10 +195,10 @@ The character encodings currently supported by Node.js include:
* `'hex'` - Encode each byte as two hexadecimal characters.
*Note*: Today's browsers follow the [WHATWG Encoding Standard][] which aliases
both 'latin1' and ISO-8859-1 to win-1252. This means that while doing something
like `http.get()`, if the returned charset is one of those listed in the WHATWG
specification it is possible that the server actually returned
Modern Web browsers follow the [WHATWG Encoding Standard][] which aliases
both `'latin1'` and `'ISO-8859-1'` to `'win-1252'`. This means that while doing
something like `http.get()`, if the returned charset is one of those listed in
the WHATWG specification it is possible that the server actually returned
win-1252-encoded data, and using `'latin1'` encoding may incorrectly decode the
characters.
@ -702,9 +702,9 @@ Returns the actual byte length of a string. This is not the same as
[`String.prototype.length`] since that returns the number of *characters* in
a string.
*Note*: For `'base64'` and `'hex'`, this function assumes valid input. For
strings that contain non-Base64/Hex-encoded data (e.g. whitespace), the return
value might be greater than the length of a `Buffer` created from the string.
For `'base64'` and `'hex'`, this function assumes valid input. For strings that
contain non-Base64/Hex-encoded data (e.g. whitespace), the return value might be
greater than the length of a `Buffer` created from the string.
Example:
@ -1948,8 +1948,8 @@ offset and cropped by the `start` and `end` indices.
Specifying `end` greater than [`buf.length`] will return the same result as
that of `end` equal to [`buf.length`].
*Note*: Modifying the new `Buffer` slice will modify the memory in the
original `Buffer` because the allocated memory of the two objects overlap.
Modifying the new `Buffer` slice will modify the memory in the original `Buffer`
because the allocated memory of the two objects overlap.
Example: Create a `Buffer` with the ASCII alphabet, take a slice, and then modify
one byte from the original `Buffer`

68
doc/api/child_process.md
View File

@ -170,9 +170,8 @@ exec('echo "The \\$HOME variable is $HOME"');
//The $HOME variable is escaped in the first instance, but not in the second
```
*Note*: Never pass unsanitized user input to this function. Any input
containing shell metacharacters may be used to trigger arbitrary command
execution.
**Never pass unsanitized user input to this function. Any input containing shell
metacharacters may be used to trigger arbitrary command execution.**
```js
const { exec } = require('child_process');
@ -218,8 +217,8 @@ If `timeout` is greater than `0`, the parent will send the signal
identified by the `killSignal` property (the default is `'SIGTERM'`) if the
child runs longer than `timeout` milliseconds.
*Note*: Unlike the exec(3) POSIX system call, `child_process.exec()` does not
replace the existing process and uses a shell to execute the command.
Unlike the exec(3) POSIX system call, `child_process.exec()` does not replace
the existing process and uses a shell to execute the command.
If this method is invoked as its [`util.promisify()`][]ed version, it returns
a Promise for an object with `stdout` and `stderr` properties. In case of an
@ -316,9 +315,9 @@ async function getVersion() {
getVersion();
```
*Note*: If the `shell` option is enabled, do not pass unsanitized user input
to this function. Any input containing shell metacharacters may be used to
trigger arbitrary command execution.
**If the `shell` option is enabled, do not pass unsanitized user input to this
function. Any input containing shell metacharacters may be used to trigger
arbitrary command execution.**
### child_process.fork(modulePath[, args][, options])
<!-- YAML
@ -376,11 +375,11 @@ Node.js processes launched with a custom `execPath` will communicate with the
parent process using the file descriptor (fd) identified using the
environment variable `NODE_CHANNEL_FD` on the child process.
*Note*: Unlike the fork(2) POSIX system call, `child_process.fork()` does
not clone the current process.
Unlike the fork(2) POSIX system call, `child_process.fork()` does not clone the
current process.
*Note*: The `shell` option available in [`child_process.spawn()`][] is not
supported by `child_process.fork()` and will be ignored if set.
The `shell` option available in [`child_process.spawn()`][] is not supported by
`child_process.fork()` and will be ignored if set.
### child_process.spawn(command[, args][, options])
<!-- YAML
@ -426,9 +425,9 @@ The `child_process.spawn()` method spawns a new process using the given
`command`, with command line arguments in `args`. If omitted, `args` defaults
to an empty array.
*Note*: If the `shell` option is enabled, do not pass unsanitized user input to
this function. Any input containing shell metacharacters may be used to
trigger arbitrary command execution.
**If the `shell` option is enabled, do not pass unsanitized user input to this
function. Any input containing shell metacharacters may be used to trigger
arbitrary command execution.**
A third argument may be used to specify additional options, with these defaults:
@ -517,12 +516,12 @@ subprocess.on('error', (err) => {
});
```
*Note*: Certain platforms (macOS, Linux) will use the value of `argv[0]` for
the process title while others (Windows, SunOS) will use `command`.
Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.
*Note*: Node.js currently overwrites `argv[0]` with `process.execPath` on
startup, so `process.argv[0]` in a Node.js child process will not match the
`argv0` parameter passed to `spawn` from the parent, retrieve it with the
Node.js currently overwrites `argv[0]` with `process.execPath` on startup, so
`process.argv[0]` in a Node.js child process will not match the `argv0`
parameter passed to `spawn` from the parent, retrieve it with the
`process.argv0` property instead.
#### options.detached
@ -725,7 +724,7 @@ until the child process has fully closed. When a timeout has been encountered
and `killSignal` is sent, the method won't return until the process has
completely exited.
*Note*: If the child process intercepts and handles the `SIGTERM` signal and
If the child process intercepts and handles the `SIGTERM` signal and
does not exit, the parent process will still wait until the child process has
exited.
@ -733,9 +732,9 @@ If the process times out or has a non-zero exit code, this method ***will***
throw an [`Error`][] that will include the full result of the underlying
[`child_process.spawnSync()`][].
*Note*: If the `shell` option is enabled, do not pass unsanitized user input
to this function. Any input containing shell metacharacters may be used to
trigger arbitrary command execution.
**If the `shell` option is enabled, do not pass unsanitized user input to this
function. Any input containing shell metacharacters may be used to trigger
arbitrary command execution.**
### child_process.execSync(command[, options])
<!-- YAML
@ -789,9 +788,8 @@ If the process times out or has a non-zero exit code, this method ***will***
throw. The [`Error`][] object will contain the entire result from
[`child_process.spawnSync()`][]
*Note*: Never pass unsanitized user input to this function. Any input
containing shell metacharacters may be used to trigger arbitrary command
execution.
**Never pass unsanitized user input to this function. Any input containing shell
metacharacters may be used to trigger arbitrary command execution.**
### child_process.spawnSync(command[, args][, options])
<!-- YAML
@ -857,9 +855,9 @@ completely exited. Note that if the process intercepts and handles the
`SIGTERM` signal and doesn't exit, the parent process will wait until the child
process has exited.
*Note*: If the `shell` option is enabled, do not pass unsanitized user input
to this function. Any input containing shell metacharacters may be used to
trigger arbitrary command execution.
**If the `shell` option is enabled, do not pass unsanitized user input to this
function. Any input containing shell metacharacters may be used to trigger
arbitrary command execution.**
## Class: ChildProcess
<!-- YAML
@ -907,9 +905,9 @@ The `'error'` event is emitted whenever:
2. The process could not be killed, or
3. Sending a message to the child process failed.
*Note*: The `'exit'` event may or may not fire after an error has occurred.
When listening to both the `'exit'` and `'error'` events, it is important
to guard against accidentally invoking handler functions multiple times.
The `'exit'` event may or may not fire after an error has occurred. When
listening to both the `'exit'` and `'error'` events, it is important to guard
against accidentally invoking handler functions multiple times.
See also [`subprocess.kill()`][] and [`subprocess.send()`][].
@ -948,7 +946,7 @@ added: v0.5.9
The `'message'` event is triggered when a child process uses [`process.send()`][]
to send messages.
*Note*: The message goes through serialization and parsing. The resulting
The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.
### subprocess.channel
@ -1111,7 +1109,7 @@ be used to send messages to the child process. When the child process is a
Node.js instance, these messages can be received via the
[`process.on('message')`][] event.
*Note*: The message goes through serialization and parsing. The resulting
The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.
For example, in the parent script:

40
doc/api/cli.md
View File

@ -53,9 +53,9 @@ changes:
Evaluate the following argument as JavaScript. The modules which are
predefined in the REPL can also be used in `script`.
*Note*: On Windows, using `cmd.exe` a single quote will not work correctly
because it only recognizes double `"` for quoting. In Powershell or
Git bash, both `'` and `"` are usable.
On Windows, using `cmd.exe` a single quote will not work correctly because it
only recognizes double `"` for quoting. In Powershell or Git bash, both `'`
and `"` are usable.
### `-p`, `--print "script"`
@ -161,9 +161,9 @@ added: v8.0.0
Emit pending deprecation warnings.
*Note*: Pending deprecations are generally identical to a runtime deprecation
with the notable exception that they are turned *off* by default and will not
be emitted unless either the `--pending-deprecation` command line flag, or the
Pending deprecations are generally identical to a runtime deprecation with the
notable exception that they are turned *off* by default and will not be emitted
unless either the `--pending-deprecation` command line flag, or the
`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
are used to provide a kind of selective "early warning" mechanism that
developers may leverage to detect deprecated API usage.
@ -183,9 +183,9 @@ added: v0.10
Aborting instead of exiting causes a core file to be generated for post-mortem
analysis using a debugger (such as `lldb`, `gdb`, and `mdb`).
*Note*: If this flag is passed, the behavior can still be set to not abort
through [`process.setUncaughtExceptionCaptureCallback()`][] (and through usage
of the `domain` module that uses it).
If this flag is passed, the behavior can still be set to not abort through
[`process.setUncaughtExceptionCaptureCallback()`][] (and through usage of the
`domain` module that uses it).
### `--trace-warnings`
<!-- YAML
@ -307,7 +307,7 @@ added: v0.1.3
Print V8 command line options.
*Note*: V8 options allow words to be separated by both dashes (`-`) or
V8 options allow words to be separated by both dashes (`-`) or
underscores (`_`).
For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`.
@ -411,7 +411,7 @@ added: v0.1.32
`':'`-separated list of directories prefixed to the module search path.
*Note*: On Windows, this is a `';'`-separated list instead.
On Windows, this is a `';'`-separated list instead.
### `NODE_DISABLE_COLORS=1`
@ -486,9 +486,9 @@ added: v8.0.0
When set to `1`, emit pending deprecation warnings.
*Note*: Pending deprecations are generally identical to a runtime deprecation
with the notable exception that they are turned *off* by default and will not
be emitted unless either the `--pending-deprecation` command line flag, or the
Pending deprecations are generally identical to a runtime deprecation with the
notable exception that they are turned *off* by default and will not be emitted
unless either the `--pending-deprecation` command line flag, or the
`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
are used to provide a kind of selective "early warning" mechanism that
developers may leverage to detect deprecated API usage.
@ -545,9 +545,9 @@ added: v7.7.0
If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's directory
containing trusted certificates.
*Note*: Be aware that unless the child environment is explicitly set, this
environment variable will be inherited by any child processes, and if they use
OpenSSL, it may cause them to trust the same CAs as node.
Be aware that unless the child environment is explicitly set, this environment
variable will be inherited by any child processes, and if they use OpenSSL, it
may cause them to trust the same CAs as node.
### `SSL_CERT_FILE=file`
<!-- YAML
@ -557,9 +557,9 @@ added: v7.7.0
If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's file
containing trusted certificates.
*Note*: Be aware that unless the child environment is explicitly set, this
environment variable will be inherited by any child processes, and if they use
OpenSSL, it may cause them to trust the same CAs as node.
Be aware that unless the child environment is explicitly set, this environment
variable will be inherited by any child processes, and if they use OpenSSL, it
may cause them to trust the same CAs as node.
### `NODE_REDIRECT_WARNINGS=file`
<!-- YAML

6
doc/api/cluster.md
View File

@ -97,9 +97,9 @@ Node.js process and a cluster worker differs:
port is random the first time, but predictable thereafter. To listen
on a unique port, generate a port number based on the cluster worker ID.
*Note*: Node.js does not provide routing logic. It is, therefore important to
design an application such that it does not rely too heavily on in-memory data
objects for things like sessions and login.
Node.js does not provide routing logic. It is, therefore important to design an
application such that it does not rely too heavily on in-memory data objects for
things like sessions and login.
Because workers are all separate processes, they can be killed or
re-spawned depending on a program's needs, without affecting other

9
doc/api/console.md
View File

@ -127,9 +127,8 @@ console.assert(false, 'Whoops %s work', 'didn\'t');
// Assertion failed: Whoops didn't work
```
*Note*: Calling `console.assert()` with a falsy assertion will only cause the
`message` to be printed to the console without interrupting execution of
subsequent code.
Calling `console.assert()` with a falsy assertion will only cause the `message`
to be printed to the console without interrupting execution of subsequent code.
### console.clear()
<!-- YAML
@ -139,8 +138,8 @@ added: v8.3.0
When `stdout` is a TTY, calling `console.clear()` will attempt to clear the
TTY. When `stdout` is not a TTY, this method does nothing.
*Note*: The specific operation of `console.clear()` can vary across operating
systems and terminal types. For most Linux operating systems, `console.clear()`
The specific operation of `console.clear()` can vary across operating systems
and terminal types. For most Linux operating systems, `console.clear()`
operates similarly to the `clear` shell command. On Windows, `console.clear()`
will clear only the output in the current terminal viewport for the Node.js
binary.

22
doc/api/crypto.md
View File

@ -1865,10 +1865,10 @@ Note that this API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications, see the
[`UV_THREADPOOL_SIZE`][] documentation for more information.
*Note*: The asynchronous version of `crypto.randomBytes()` is carried out
in a single threadpool request. To minimize threadpool task length variation,
partition large `randomBytes` requests when doing so as part of fulfilling a
client request.
The asynchronous version of `crypto.randomBytes()` is carried out in a single
threadpool request. To minimize threadpool task length variation, partition
large `randomBytes` requests when doing so as part of fulfilling a client
request.
### crypto.randomFillSync(buffer[, offset][, size])
<!-- YAML
@ -1977,10 +1977,10 @@ Note that this API uses libuv's threadpool, which can have surprising and
negative performance implications for some applications, see the
[`UV_THREADPOOL_SIZE`][] documentation for more information.
*Note*: The asynchronous version of `crypto.randomFill()` is carried out
in a single threadpool request. To minimize threadpool task length variation,
partition large `randomFill` requests when doing so as part of fulfilling a
client request.
The asynchronous version of `crypto.randomFill()` is carried out in a single
threadpool request. To minimize threadpool task length variation, partition
large `randomFill` requests when doing so as part of fulfilling a client
request.
### crypto.setEngine(engine[, flags])
<!-- YAML
@ -2036,9 +2036,9 @@ comparing HMAC digests or secret values like authentication cookies or
`a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they
must have the same length.
*Note*: Use of `crypto.timingSafeEqual` does not guarantee that the
*surrounding* code is timing-safe. Care should be taken to ensure that the
surrounding code does not introduce timing vulnerabilities.
Use of `crypto.timingSafeEqual` does not guarantee that the *surrounding* code
is timing-safe. Care should be taken to ensure that the surrounding code does
not introduce timing vulnerabilities.
## Notes

26
doc/api/deprecations.md
View File

@ -544,8 +544,8 @@ Type: Documentation-only
The `http` module `ServerResponse.prototype.writeHeader()` API has been
deprecated. Please use `ServerResponse.prototype.writeHead()` instead.
*Note*: The `ServerResponse.prototype.writeHeader()` method was never
documented as an officially supported API.
The `ServerResponse.prototype.writeHeader()` method was never documented as an
officially supported API.
<a id="DEP0064"></a>
### DEP0064: tls.createSecurePair()
@ -581,8 +581,8 @@ properties have been deprecated. Please instead use one of the public methods
`outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working
with outgoing headers.
*Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were
never documented as officially supported properties.
The `outgoingMessage._headers` and `outgoingMessage._headerNames` properties
were never documented as officially supported properties.
<a id="DEP0067"></a>
### DEP0067: OutgoingMessage.prototype.\_renderHeaders
@ -592,7 +592,7 @@ Type: Documentation-only
The `http` module `OutgoingMessage.prototype._renderHeaders()` API has been
deprecated.
*Note*: `OutgoingMessage.prototype._renderHeaders` was never documented as
The `OutgoingMessage.prototype._renderHeaders` property was never documented as
an officially supported API.
<a id="DEP0068"></a>
@ -610,7 +610,7 @@ Type: End-of-Life
DebugContext has been removed in V8 and is not available in Node 10+.
*Note*: DebugContext was an experimental API.
DebugContext was an experimental API.
<a id="DEP0070"></a>
### DEP0070: async_hooks.currentId()
@ -620,7 +620,7 @@ Type: End-of-Life
`async_hooks.currentId()` was renamed to `async_hooks.executionAsyncId()` for
clarity.
*Note*: change was made while `async_hooks` was an experimental API.
This change was made while `async_hooks` was an experimental API.
<a id="DEP0071"></a>
### DEP0071: async_hooks.triggerId()
@ -630,7 +630,7 @@ Type: End-of-Life
`async_hooks.triggerId()` was renamed to `async_hooks.triggerAsyncId()` for
clarity.
*Note*: change was made while `async_hooks` was an experimental API.
This change was made while `async_hooks` was an experimental API.
<a id="DEP0072"></a>
### DEP0072: async_hooks.AsyncResource.triggerId()
@ -640,7 +640,7 @@ Type: End-of-Life
`async_hooks.AsyncResource.triggerId()` was renamed to
`async_hooks.AsyncResource.triggerAsyncId()` for clarity.
*Note*: change was made while `async_hooks` was an experimental API.
This change was made while `async_hooks` was an experimental API.
<a id="DEP0073"></a>
### DEP0073: Several internal properties of net.Server
@ -650,8 +650,8 @@ Type: End-of-Life
Accessing several internal, undocumented properties of `net.Server` instances
with inappropriate names has been deprecated.
*Note*: As the original API was undocumented and not generally useful for
non-internal code, no replacement API is provided.
As the original API was undocumented and not generally useful for non-internal
code, no replacement API is provided.
<a id="DEP0074"></a>
### DEP0074: REPLServer.bufferedCommand
@ -681,7 +681,7 @@ const querystring = require('querystring');
querystring.parse(str, '\n', '=');
```
*Note*: This function is not completely equivalent to `querystring.parse()`. One
This function is not completely equivalent to `querystring.parse()`. One
difference is that `querystring.parse()` does url decoding:
```sh
@ -698,7 +698,7 @@ Type: Runtime
`Module._debug()` has been deprecated.
*Note*: `Module._debug()` was never documented as an officially supported API.
The `Module._debug()` function was never documented as an officially supported API.
<a id="DEP0078"></a>
### DEP0078: REPLServer.turnOffEditorMode()

6
doc/api/documentation.md
View File

@ -55,9 +55,9 @@ The API has proven satisfactory. Compatibility with the npm ecosystem
is a high priority, and will not be broken unless absolutely necessary.
```
*Note*: Caution must be used when making use of `Experimental` features,
particularly within modules that may be used as dependencies (or dependencies
of dependencies) within a Node.js application. End users may not be aware that
Caution must be used when making use of `Experimental` features, particularly
within modules that may be used as dependencies (or dependencies of
dependencies) within a Node.js application. End users may not be aware that
experimental features are being used, and therefore may experience unexpected
failures or behavior changes when API modifications occur. To help avoid such
surprises, `Experimental` features may require a command-line flag to

2
doc/api/errors.md
View File

@ -1307,7 +1307,7 @@ A failure occurred resolving imports in an [ES6 module][].
A callback was called more than once.
*Note*: A callback is almost always meant to only be called once as the query
A callback is almost always meant to only be called once as the query
can either be fulfilled or rejected but not both at the same time. The latter
would be possible by calling a callback more than once.

107
doc/api/fs.md
View File

@ -86,8 +86,8 @@ be omitted, in which case a default callback is used that rethrows errors. To
get a trace to the original call site, set the `NODE_DEBUG` environment
variable:
*Note*: Omitting the callback function on asynchronous fs functions is
deprecated and may result in an error being thrown in the future.
Omitting the callback function on asynchronous fs functions is deprecated and
may result in an error being thrown in the future.
```txt
$ cat script.js
@ -178,7 +178,7 @@ const fileUrl = new URL('file:///tmp/hello');
fs.readFileSync(fileUrl);
```
*Note*: `file:` URLs are always absolute paths.
`file:` URLs are always absolute paths.
Using WHATWG [`URL`][] objects might introduce platform-specific behaviors.
@ -203,7 +203,7 @@ fs.readFileSync(new URL('file:///c/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute
```
*Note*: `file:` URLs with drive letters must use `:` as a separator just after
`file:` URLs with drive letters must use `:` as a separator just after
the drive letter. Using another separator will result in a throw.
On all other platforms, `file:` URLs with a hostname are unsupported and will
@ -471,7 +471,7 @@ Returns `true` if the `fs.Stats` object describes a socket.
Returns `true` if the `fs.Stats` object describes a symbolic link.
*Note*: This method is only valid when using [`fs.lstat()`][]
This method is only valid when using [`fs.lstat()`][]
### stats.dev
@ -581,12 +581,13 @@ The timestamp indicating the creation time of this file.
### Stat Time Values
*Note*: `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` are [numbers][MDN-Number]
that hold the corresponding times in milliseconds. Their precision is platform
specific. `atime`, `mtime`, `ctime`, and `birthtime` are [`Date`][MDN-Date]
object alternate representations of the various times. The `Date` and number
values are not connected. Assigning a new number value, or mutating the `Date`
value, will not be reflected in the corresponding alternate representation.
The `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` properties are
[numbers][MDN-Number] that hold the corresponding times in milliseconds. Their
precision is platform specific. `atime`, `mtime`, `ctime`, and `birthtime` are
[`Date`][MDN-Date] object alternate representations of the various times. The
`Date` and number values are not connected. Assigning a new number value, or
mutating the `Date` value, will not be reflected in the corresponding alternate
representation.
The times in the stat object have the following semantics:
@ -1679,8 +1680,8 @@ changes:
Change the file system timestamps of the object referenced by the supplied file
descriptor. See [`fs.utimes()`][].
*Note*: This function does not work on AIX versions before 7.1, it will return
the error `UV_ENOSYS`.
This function does not work on AIX versions before 7.1, it will return the
error `UV_ENOSYS`.
## fs.futimesSync(fd, atime, mtime)
<!-- YAML
@ -1918,10 +1919,10 @@ fs.mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, folder) => {
});
```
*Note*: The `fs.mkdtemp()` method will append the six randomly selected
characters directly to the `prefix` string. For instance, given a directory
`/tmp`, if the intention is to create a temporary directory *within* `/tmp`,
the `prefix` *must* end with a trailing platform-specific path separator
The `fs.mkdtemp()` method will append the six randomly selected characters
directly to the `prefix` string. For instance, given a directory `/tmp`, if the
intention is to create a temporary directory *within* `/tmp`, the `prefix`
*must* end with a trailing platform-specific path separator
(`require('path').sep`).
```js
@ -2038,8 +2039,8 @@ On Linux, positional writes don't work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.
*Note*: The behavior of `fs.open()` is platform-specific for some flags. As
such, opening a directory on macOS and Linux with the `'a+'` flag - see example
The behavior of `fs.open()` is platform-specific for some flags. As such,
opening a directory on macOS and Linux with the `'a+'` flag - see example
below - will return an error. In contrast, on Windows and FreeBSD, a file
descriptor will be returned.
@ -2228,10 +2229,11 @@ If `options` is a string, then it specifies the encoding. Example:
```js
fs.readFile('/etc/passwd', 'utf8', callback);
```
*Note*: When the path is a directory, the behavior of
`fs.readFile()` and [`fs.readFileSync()`][] is platform-specific. On macOS,
Linux, and Windows, an error will be returned. On FreeBSD, a representation
of the directory's contents will be returned.
When the path is a directory, the behavior of `fs.readFile()` and
[`fs.readFileSync()`][] is platform-specific. On macOS, Linux, and Windows, an
error will be returned. On FreeBSD, a representation of the directory's contents
will be returned.
```js
// macOS, Linux, and Windows
@ -2247,12 +2249,11 @@ fs.readFile('<directory>', (err, data) => {
Any specified file descriptor has to support reading.
*Note*: If a file descriptor is specified as the `path`, it will not be closed
If a file descriptor is specified as the `path`, it will not be closed
automatically.
*Note*: `fs.readFile()` buffers the entire file.
To minimize memory costs, when possible prefer streaming via
`fs.createReadStream()`.
The `fs.readFile()` function buffers the entire file. To minimize memory costs,
when possible prefer streaming via `fs.createReadStream()`.
## fs.readFileSync(path[, options])
<!-- YAML
@ -2277,8 +2278,8 @@ Synchronous version of [`fs.readFile()`][]. Returns the contents of the `path`.
If the `encoding` option is specified then this function returns a
string. Otherwise it returns a buffer.
*Note*: Similar to [`fs.readFile()`][], when the path is a directory, the
behavior of `fs.readFileSync()` is platform-specific.
Similar to [`fs.readFile()`][], when the path is a directory, the behavior of
`fs.readFileSync()` is platform-specific.
```js
// macOS, Linux, and Windows
@ -2410,8 +2411,8 @@ object with an `encoding` property specifying the character encoding to use for
the path passed to the callback. If the `encoding` is set to `'buffer'`,
the path returned will be passed as a `Buffer` object.
*Note*: If `path` resolves to a socket or a pipe, the function will return a
system dependent name for that object.
If `path` resolves to a socket or a pipe, the function will return a system
dependent name for that object.
## fs.realpath.native(path[, options], callback)
<!-- YAML
@ -2436,9 +2437,9 @@ object with an `encoding` property specifying the character encoding to use for
the path passed to the callback. If the `encoding` is set to `'buffer'`,
the path returned will be passed as a `Buffer` object.
*Note*: On Linux, when Node.js is linked against musl libc, the procfs file
system must be mounted on `/proc` in order for this function to work. Glibc
does not have this restriction.
On Linux, when Node.js is linked against musl libc, the procfs file system must
be mounted on `/proc` in order for this function to work. Glibc does not have
this restriction.
## fs.realpathSync(path[, options])
<!-- YAML
@ -2482,8 +2483,8 @@ object with an `encoding` property specifying the character encoding to use for
the returned value. If the `encoding` is set to `'buffer'`, the path returned
will be passed as a `Buffer` object.
*Note*: If `path` resolves to a socket or a pipe, the function will return a
system dependent name for that object.
If `path` resolves to a socket or a pipe, the function will return a system
dependent name for that object.
## fs.realpathSync.native(path[, options])
<!-- YAML
@ -2503,9 +2504,9 @@ object with an `encoding` property specifying the character encoding to use for
the path passed to the callback. If the `encoding` is set to `'buffer'`,
the path returned will be passed as a `Buffer` object.
*Note*: On Linux, when Node.js is linked against musl libc, the procfs file
system must be mounted on `/proc` in order for this function to work. Glibc
does not have this restriction.
On Linux, when Node.js is linked against musl libc, the procfs file system must
be mounted on `/proc` in order for this function to work. Glibc does not have
this restriction.
## fs.rename(oldPath, newPath, callback)
<!-- YAML
@ -2567,8 +2568,8 @@ changes:
Asynchronous rmdir(2). No arguments other than a possible exception are given
to the completion callback.
*Note*: Using `fs.rmdir()` on a file (not a directory) results in an `ENOENT`
error on Windows and an `ENOTDIR` error on POSIX.
Using `fs.rmdir()` on a file (not a directory) results in an `ENOENT` error on
Windows and an `ENOTDIR` error on POSIX.
## fs.rmdirSync(path)
<!-- YAML
@ -2584,8 +2585,8 @@ changes:
Synchronous rmdir(2). Returns `undefined`.
*Note*: Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT`
error on Windows and an `ENOTDIR` error on POSIX.
Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` error
on Windows and an `ENOTDIR` error on POSIX.
## fs.stat(path, callback)
<!-- YAML
@ -2701,8 +2702,8 @@ Asynchronous truncate(2). No arguments other than a possible exception are
given to the completion callback. A file descriptor can also be passed as the
first argument. In this case, `fs.ftruncate()` is called.
*Note*: Passing a file descriptor is deprecated and may result in an error
being thrown in the future.
Passing a file descriptor is deprecated and may result in an error being thrown
in the future.
## fs.truncateSync(path[, len])
<!-- YAML
@ -2715,8 +2716,8 @@ added: v0.8.6
Synchronous truncate(2). Returns `undefined`. A file descriptor can also be
passed as the first argument. In this case, `fs.ftruncateSync()` is called.
*Note*: Passing a file descriptor is deprecated and may result in an error
being thrown in the future.
Passing a file descriptor is deprecated and may result in an error being thrown
in the future.
## fs.unlink(path, callback)
<!-- YAML
@ -2769,7 +2770,7 @@ effectively stopping watching of `filename`.
Calling `fs.unwatchFile()` with a filename that is not being watched is a
no-op, not an error.
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and
Using [`fs.watch()`][] is more efficient than `fs.watchFile()` and
`fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()`
and `fs.unwatchFile()` when possible.
@ -2986,18 +2987,18 @@ These stat objects are instances of `fs.Stat`.
To be notified when the file was modified, not just accessed, it is necessary
to compare `curr.mtime` and `prev.mtime`.
*Note*: When an `fs.watchFile` operation results in an `ENOENT` error, it
When an `fs.watchFile` operation results in an `ENOENT` error, it
will invoke the listener once, with all the fields zeroed (or, for dates, the
Unix Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`,
instead of zero. If the file is created later on, the listener will be called
again, with the latest stat objects. This is a change in functionality since
v0.10.
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile` and
Using [`fs.watch()`][] is more efficient than `fs.watchFile` and
`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
`fs.unwatchFile` when possible.
*Note:* When a file being watched by `fs.watchFile()` disappears and reappears,
When a file being watched by `fs.watchFile()` disappears and reappears,
then the `previousStat` reported in the second callback event (the file's
reappearance) will be the same as the `previousStat` of the first callback
event (its disappearance).
@ -3154,7 +3155,7 @@ Note that it is unsafe to use `fs.writeFile` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.
*Note*: If a file descriptor is specified as the `file`, it will not be closed
If a file descriptor is specified as the `file`, it will not be closed
automatically.
## fs.writeFileSync(file, data[, options])
@ -4207,7 +4208,7 @@ without waiting for the `Promise` to be resolved (or rejected).
The following constants are exported by `fs.constants`.
*Note*: Not every constant will be available on every operating system.
Not every constant will be available on every operating system.
### File Access Constants

16
doc/api/http.md
View File

@ -307,7 +307,7 @@ Until the data is consumed, the `'end'` event will not fire. Also, until
the data is read it will consume memory that can eventually lead to a
'process out of memory' error.
*Note*: Node.js does not check whether Content-Length and the length of the
Node.js does not check whether Content-Length and the length of the
body which has been transmitted are equal or not.
The request implements the [Writable Stream][] interface. This is an
@ -816,7 +816,7 @@ access this event. In particular, the socket will not emit `'readable'` events
because of how the protocol parser attaches to the socket. The `socket` can
also be accessed at `request.connection`.
*Note*: This event can also be explicitly emitted by users to inject connections
This event can also be explicitly emitted by users to inject connections
into the HTTP server. In that case, any [`Duplex`][] stream can be passed.
### Event: 'request'
@ -915,7 +915,7 @@ to have timed out.
A value of `0` will disable the timeout behavior on incoming connections.
*Note*: The socket timeout logic is set up on connection, so changing this
The socket timeout logic is set up on connection, so changing this
value only affects new connections to the server, not any existing connections.
### server.keepAliveTimeout
@ -935,8 +935,8 @@ A value of `0` will disable the keep-alive timeout behavior on incoming connecti
A value of `0` makes the http server behave similarly to Node.js versions prior to 8.0.0,
which did not have a keep-alive timeout.
*Note*: The socket timeout logic is set up on connection, so changing this
value only affects new connections to the server, not any existing connections.
The socket timeout logic is set up on connection, so changing this value only
affects new connections to the server, not any existing connections.
## Class: http.ServerResponse
<!-- YAML
@ -1086,7 +1086,7 @@ header-related http module methods. The keys of the returned object are the
header names and the values are the respective header values. All header names
are lowercase.
*Note*: The object returned by the `response.getHeaders()` method _does not_
The object returned by the `response.getHeaders()` method _does not_
prototypically inherit from the JavaScript `Object`. This means that typical
`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others
are not defined and *will not work*.
@ -1305,8 +1305,8 @@ the second parameter specifies how to encode it into a byte stream.
By default the `encoding` is `'utf8'`. `callback` will be called when this chunk
of data is flushed.
*Note*: This is the raw HTTP body and has nothing to do with
higher-level multi-part body encodings that may be used.
This is the raw HTTP body and has nothing to do with higher-level multi-part
body encodings that may be used.
The first time [`response.write()`][] is called, it will send the buffered
header information and the first chunk of the body to the client. The second

97
doc/api/http2.md
View File

@ -135,7 +135,7 @@ added: v8.4.0
The `'connect'` event is emitted once the `Http2Session` has been successfully
connected to the remote peer and communication may begin.
*Note*: User code will typically not listen for this event directly.
User code will typically not listen for this event directly.
#### Event: 'error'
<!-- YAML
@ -181,8 +181,8 @@ the handler function will receive three arguments:
* `opaqueData` {Buffer} If additional opaque data was included in the GOAWAY
frame, a `Buffer` instance will be passed containing that data.
*Note*: The `Http2Session` instance will be shut down automatically when the
`'goaway'` event is emitted.
The `Http2Session` instance will be shut down automatically when the `'goaway'`
event is emitted.
#### Event: 'localSettings'
<!-- YAML
@ -193,9 +193,8 @@ The `'localSettings'` event is emitted when an acknowledgment SETTINGS frame
has been received. When invoked, the handler function will receive a copy of
the local settings.
*Note*: When using `http2session.settings()` to submit new settings, the
modified settings do not take effect until the `'localSettings'` event is
emitted.
When using `http2session.settings()` to submit new settings, the modified
settings do not take effect until the `'localSettings'` event is emitted.
```js
session.settings({ enablePush: false });
@ -540,10 +539,9 @@ Once called, the `http2session.pendingSettingsAck` property will be `true`
while the session is waiting for the remote peer to acknowledge the new
settings.
*Note*: The new settings will not become effective until the SETTINGS
acknowledgment is received and the `'localSettings'` event is emitted. It
is possible to send multiple SETTINGS frames while acknowledgment is still
pending.
The new settings will not become effective until the SETTINGS acknowledgment is
received and the `'localSettings'` event is emitted. It is possible to send
multiple SETTINGS frames while acknowledgment is still pending.
#### http2session.type
<!-- YAML
@ -718,10 +716,9 @@ queuing the last chunk of payload data to be sent. The callback is passed a
single object (with a `null` prototype) that the listener may use to specify
the trailing header fields to send to the peer.
*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2
pseudo-header fields (e.g. `':method'`, `':path'`, etc). An `'error'` event
will be emitted if the `getTrailers` callback attempts to set such header
fields.
The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
fields (e.g. `':method'`, `':path'`, etc). An `'error'` event will be emitted
if the `getTrailers` callback attempts to set such header fields.
The `:method` and `:path` pseudo-headers are not specified within `headers`,
they respectively default to:
@ -749,7 +746,7 @@ On the client, `Http2Stream` instances are created and returned when either the
`http2session.request()` method is called, or in response to an incoming
`'push'` event.
*Note*: The `Http2Stream` class is a base for the [`ServerHttp2Stream`][] and
The `Http2Stream` class is a base for the [`ServerHttp2Stream`][] and
[`ClientHttp2Stream`][] classes, each of which is used specifically by either
the Server or Client side, respectively.
@ -770,14 +767,13 @@ when:
On the client side, instances of [`ClientHttp2Stream`][] are created when the
`http2session.request()` method is called.
*Note*: On the client, the `Http2Stream` instance returned by
`http2session.request()` may not be immediately ready for use if the parent
`Http2Session` has not yet been fully established. In such cases, operations
called on the `Http2Stream` will be buffered until the `'ready'` event is
emitted. User code should rarely, if ever, need to handle the `'ready'`
event directly. The ready status of an `Http2Stream` can be determined by
checking the value of `http2stream.id`. If the value is `undefined`, the stream
is not yet ready for use.
On the client, the `Http2Stream` instance returned by `http2session.request()`
may not be immediately ready for use if the parent `Http2Session` has not yet
been fully established. In such cases, operations called on the `Http2Stream`
will be buffered until the `'ready'` event is emitted. User code should rarely,
if ever, need to handle the `'ready'` event directly. The ready status of an
`Http2Stream` can be determined by checking the value of `http2stream.id`. If
the value is `undefined`, the stream is not yet ready for use.
##### Destruction
@ -809,8 +805,8 @@ added: v8.4.0
The `'aborted'` event is emitted whenever a `Http2Stream` instance is
abnormally aborted in mid-communication.
*Note*: The `'aborted'` event will only be emitted if the `Http2Stream`
writable side has not been ended.
The `'aborted'` event will only be emitted if the `Http2Stream` writable side
has not been ended.
#### Event: 'close'
<!-- YAML
@ -1231,10 +1227,9 @@ server.on('stream', (stream) => {
});
```
*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2
pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event
will be emitted if the `getTrailers` callback attempts to set such header
fields.
The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted
if the `getTrailers` callback attempts to set such header fields.
#### http2stream.respondWithFD(fd[, headers[, options]])
<!-- YAML
@ -1315,10 +1310,9 @@ server.on('stream', (stream) => {
server.on('close', () => fs.closeSync(fd));
```
*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2
pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event
will be emitted if the `getTrailers` callback attempts to set such header
fields.
The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted
if the `getTrailers` callback attempts to set such header fields.
#### http2stream.respondWithFile(path[, headers[, options]])
<!-- YAML
@ -1424,10 +1418,9 @@ server.on('stream', (stream) => {
});
```
*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2
pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event
will be emitted if the `getTrailers` callback attempts to set such header
fields.
The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted
if the `getTrailers` callback attempts to set such header fields.
### Class: Http2Server
<!-- YAML
@ -2005,8 +1998,8 @@ const headers = {
stream.respond(headers);
```
*Note*: Header objects passed to callback functions will have a `null`
prototype. This means that normal JavaScript object methods such as
Header objects passed to callback functions will have a `null` prototype. This
means that normal JavaScript object methods such as
`Object.prototype.toString()` and `Object.prototype.hasOwnProperty()` will
not work.
@ -2078,9 +2071,8 @@ const server = http2.createServer({
});
```
*Note*: The `options.selectPadding` function is invoked once for *every*
HEADERS and DATA frame. This has a definite noticeable impact on
performance.
The `options.selectPadding` function is invoked once for *every* HEADERS and
DATA frame. This has a definite noticeable impact on performance.
### Error Handling
@ -2310,8 +2302,8 @@ added: v8.4.0
The `'aborted'` event is emitted whenever a `Http2ServerRequest` instance is
abnormally aborted in mid-communication.
*Note*: The `'aborted'` event will only be emitted if the
`Http2ServerRequest` writable side has not been ended.
The `'aborted'` event will only be emitted if the `Http2ServerRequest` writable
side has not been ended.
#### Event: 'close'
<!-- YAML
@ -2357,12 +2349,11 @@ console.log(request.headers);
See [HTTP2 Headers Object][].
*Note*: In HTTP/2, the request path, hostname, protocol, and method are
represented as special headers prefixed with the `:` character (e.g. `':path'`).
These special headers will be included in the `request.headers` object. Care
must be taken not to inadvertently modify these special headers or errors may
occur. For instance, removing all headers from the request will cause errors
to occur:
In HTTP/2, the request path, hostname, protocol, and method are represented as
special headers prefixed with the `:` character (e.g. `':path'`). These special
headers will be included in the `request.headers` object. Care must be taken not
to inadvertently modify these special headers or errors may occur. For instance,
removing all headers from the request will cause errors to occur:
```js
removeAllHeaders(request.headers);
@ -2694,7 +2685,7 @@ header-related http module methods. The keys of the returned object are the
header names and the values are the respective header values. All header names
are lowercase.
*Note*: The object returned by the `response.getHeaders()` method _does not_
The object returned by the `response.getHeaders()` method _does not_
prototypically inherit from the JavaScript `Object`. This means that typical
`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others
are not defined and *will not work*.
@ -2922,8 +2913,8 @@ the second parameter specifies how to encode it into a byte stream.
By default the `encoding` is `'utf8'`. `callback` will be called when this chunk
of data is flushed.
*Note*: This is the raw HTTP body and has nothing to do with
higher-level multi-part body encodings that may be used.
This is the raw HTTP body and has nothing to do with higher-level multi-part
body encodings that may be used.
The first time [`response.write()`][] is called, it will send the buffered
header information and the first chunk of the body to the client. The second

4
doc/api/intl.md
View File

@ -56,8 +56,8 @@ option:
| [REPL][] | partial (inaccurate line editing) | full | full | full |
| [`require('util').TextDecoder`][] | partial (basic encodings support) | partial/full (depends on OS) | partial (Unicode-only) | full |
*Note*: The "(not locale-aware)" designation denotes that the function carries
out its operation just like the non-`Locale` version of the function, if one
The "(not locale-aware)" designation denotes that the function carries out its
operation just like the non-`Locale` version of the function, if one
exists. For example, under `none` mode, `Date.prototype.toLocaleString()`'s
operation is identical to that of `Date.prototype.toString()`.

20
doc/api/modules.md
View File

@ -352,9 +352,9 @@ If this was in a folder at `./some-library`, then
This is the extent of Node.js's awareness of package.json files.
*Note*: If the file specified by the `"main"` entry of `package.json` is
missing and can not be resolved, Node.js will report the entire module as
missing with the default error:
If the file specified by the `"main"` entry of `package.json` is missing and
can not be resolved, Node.js will report the entire module as missing with the
default error:
```txt
Error: Cannot find module 'some-library'
@ -407,7 +407,7 @@ If the `NODE_PATH` environment variable is set to a colon-delimited list
of absolute paths, then Node.js will search those paths for modules if they
are not found elsewhere.
*Note*: On Windows, `NODE_PATH` is delimited by semicolons instead of colons.
On Windows, `NODE_PATH` is delimited by semicolons (`;`) instead of colons.
`NODE_PATH` was originally created to support loading modules from
varying paths before the current [module resolution][] algorithm was frozen.
@ -430,8 +430,8 @@ configured `node_prefix`.
These are mostly for historic reasons.
*Note*: It is strongly encouraged to place dependencies in the local
`node_modules` folder. These will be loaded faster, and more reliably.
It is strongly encouraged to place dependencies in the local `node_modules`
folder. These will be loaded faster, and more reliably.
## The module wrapper
@ -816,10 +816,10 @@ added: v0.5.1
The `module.require` method provides a way to load a module as if
`require()` was called from the original module.
*Note*: In order to do this, it is necessary to get a reference to the
`module` object. Since `require()` returns the `module.exports`, and the
`module` is typically *only* available within a specific module's code, it must
be explicitly exported in order to be used.
In order to do this, it is necessary to get a reference to the `module` object.
Since `require()` returns the `module.exports`, and the `module` is typically
*only* available within a specific module's code, it must be explicitly exported
in order to be used.
## The `Module` Object

46
doc/api/n-api.md
View File

@ -250,9 +250,9 @@ typedef struct napi_extended_error_info {
[`napi_get_last_error_info`][] returns the information for the last
N-API call that was made.
*Note*: Do not rely on the content or format of any of the extended
information as it is not subject to SemVer and may change at any time.
It is intended only for logging purposes.
Do not rely on the content or format of any of the extended information as it
is not subject to SemVer and may change at any time. It is intended only for
logging purposes.
#### napi_get_last_error_info
<!-- YAML
@ -272,12 +272,12 @@ Returns `napi_ok` if the API succeeded.
This API retrieves a `napi_extended_error_info` structure with information
about the last error that occurred.
*Note*: The content of the `napi_extended_error_info` returned is only
valid up until an n-api function is called on the same `env`.
The content of the `napi_extended_error_info` returned is only valid up until
an n-api function is called on the same `env`.
*Note*: Do not rely on the content or format of any of the extended
information as it is not subject to SemVer and may change at any time.
It is intended only for logging purposes.
Do not rely on the content or format of any of the extended information as it
is not subject to SemVer and may change at any time. It is intended only for
logging purposes.
### Exceptions
@ -1169,9 +1169,9 @@ later by native code. The API allows the caller to pass in a finalize callback,
in case the underlying native resource needs to be cleaned up when the external
JavaScript value gets collected.
*Note*: The created value is not an object, and therefore does not support
additional properties. It is considered a distinct value type: calling
`napi_typeof()` with an external value yields `napi_external`.
The created value is not an object, and therefore does not support additional
properties. It is considered a distinct value type: calling `napi_typeof()` with
an external value yields `napi_external`.
#### napi_create_external_arraybuffer
<!-- YAML
@ -1236,7 +1236,7 @@ This API allocates a `node::Buffer` object and initializes it with data
backed by the passed in buffer. While this is still a fully-supported data
structure, in most cases using a TypedArray will suffice.
*Note*: For Node.js >=4 `Buffers` are Uint8Arrays.
For Node.js >=4 `Buffers` are Uint8Arrays.
#### napi_create_function
<!-- YAML
@ -2850,10 +2850,9 @@ This API allows an add-on author to create a function object in native code.
This is the primary mechanism to allow calling *into* the add-on's native code
*from* JavaScript.
*Note*: The newly created function is not automatically visible from
script after this call. Instead, a property must be explicitly set on any
object that is visible to JavaScript, in order for the function to be accessible
from script.
The newly created function is not automatically visible from script after this
call. Instead, a property must be explicitly set on any object that is visible
to JavaScript, in order for the function to be accessible from script.
In order to expose a function as part of the
add-on's module exports, set the newly created function on the exports
@ -2886,7 +2885,7 @@ const myaddon = require('./addon');
myaddon.sayHello();
```
*Note*: The string passed to require is not necessarily the name passed into
The string passed to require is not necessarily the name passed into
`NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp`
responsible for creating the `.node` file.
@ -3142,8 +3141,8 @@ invocation. (If it is deleted before then, then the finalize callback may never
be invoked.) Therefore, when obtaining a reference a finalize callback is also
required in order to enable correct proper of the reference.
*Note*: This API may modify the prototype chain of the wrapper object.
Afterward, additional manipulation of the wrapper's prototype chain may cause
This API may modify the prototype chain of the wrapper object. Afterward,
additional manipulation of the wrapper's prototype chain may cause
`napi_unwrap()` to fail.
Calling napi_wrap() a second time on an object will return an error. To associate
@ -3284,11 +3283,10 @@ required.
`async_resource_name` should be a null-terminated, UTF-8-encoded string.
*Note*: The `async_resource_name` identifier is provided by the user and should
be representative of the type of async work being performed. It is also
recommended to apply namespacing to the identifier, e.g. by including the
module name. See the [`async_hooks` documentation][async_hooks `type`]
for more information.
The `async_resource_name` identifier is provided by the user and should be
representative of the type of async work being performed. It is also recommended
to apply namespacing to the identifier, e.g. by including the module name. See
the [`async_hooks` documentation][async_hooks `type`] for more information.
### napi_delete_async_work
<!-- YAML

21
doc/api/net.md
View File

@ -194,14 +194,11 @@ length of the queue of pending connections. The actual length will be determined
by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn`
on Linux. The default value of this parameter is 511 (not 512).
All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for details).
*Note*:
* All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for
details).
* The `server.listen()` method can be called again if and only if there was an error
during the first `server.listen()` call or `server.close()` has been called.
Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown.
The `server.listen()` method can be called again if and only if there was an error
during the first `server.listen()` call or `server.close()` has been called.
Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown.
One of the most common errors raised when listening is `EADDRINUSE`.
This happens when another server is already listening on the requested
@ -237,7 +234,7 @@ The `handle` object can be either a server, a socket (anything with an
underlying `_handle` member), or an object with an `fd` member that is a
valid file descriptor.
*Note*: Listening on a file descriptor is not supported on Windows.
Listening on a file descriptor is not supported on Windows.
#### server.listen(options[, callback])
<!-- YAML
@ -309,9 +306,9 @@ If `host` is omitted, the server will accept connections on the
[unspecified IPv6 address][] (`::`) when IPv6 is available, or the
[unspecified IPv4 address][] (`0.0.0.0`) otherwise.
*Note*: In most operating systems, listening to the
[unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
the [unspecified IPv4 address][] (`0.0.0.0`).
In most operating systems, listening to the [unspecified IPv6 address][] (`::`)
may cause the `net.Server` to also listen on the [unspecified IPv4 address][]
(`0.0.0.0`).
### server.listening
<!-- YAML
@ -885,7 +882,7 @@ Possible signatures:
* [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`]
for TCP connections.
*Note*: The [`net.connect()`][] function is an alias to this function.
The [`net.connect()`][] function is an alias to this function.
### net.createConnection(options[, connectListener])
<!-- YAML

18
doc/api/os.md
View File

@ -166,8 +166,8 @@ For example:
]
```
*Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values
of all processors are always 0.
Because `nice` values are UNIX-specific, on Windows the `nice` values of all
processors are always 0.
## os.endianness()
<!-- YAML
@ -322,8 +322,8 @@ Currently possible values are:
Equivalent to [`process.platform`][].
*Note*: The value `'android'` may also be returned if the Node.js is built on
the Android operating system. However, Android support in Node.js is considered
The value `'android'` may also be returned if the Node.js is built on the
Android operating system. However, Android support in Node.js is considered
to be experimental at this time.
## os.release()
@ -336,8 +336,8 @@ added: v0.3.3
The `os.release()` method returns a string identifying the operating system
release.
*Note*: On POSIX systems, the operating system release is determined by
calling [uname(3)][]. On Windows, `GetVersionExW()` is used. Please see
On POSIX systems, the operating system release is determined by calling
[uname(3)][]. On Windows, `GetVersionExW()` is used. Please see
https://en.wikipedia.org/wiki/Uname#Examples for more information.
## os.tmpdir()
@ -389,8 +389,8 @@ added: v0.3.3
The `os.uptime()` method returns the system uptime in number of seconds.
*Note*: On Windows the returned value includes fractions of a second.
Use `Math.floor()` to get whole seconds.
On Windows the returned value includes fractions of a second. Use `Math.floor()`
to get whole seconds.
## os.userInfo([options])
<!-- YAML
@ -417,7 +417,7 @@ operating system response.
The following constants are exported by `os.constants`.
*Note*: Not all constants will be available on every operating system.
Not all constants will be available on every operating system.
### Signal Constants
<!-- YAML

6
doc/api/path.md
View File

@ -539,9 +539,9 @@ On Windows:
// Returns: ['foo', 'bar', 'baz']
```
*Note*: On Windows, both the forward slash (`/`) and backward slash (`\`) are
accepted as path segment separators; however, the `path` methods only add
backward slashes (`\`).
On Windows, both the forward slash (`/`) and backward slash (`\`) are accepted
as path segment separators; however, the `path` methods only add backward
slashes (`\`).
## path.toNamespacedPath(path)
<!-- YAML

127
doc/api/process.md
View File

@ -94,8 +94,8 @@ The listener callback is invoked with the following arguments:
* `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or
undefined.
*Note*: The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.
The message goes through serialization and parsing. The resulting message might
not be the same as what is originally sent.
### Event: 'rejectionHandled'
<!-- YAML
@ -406,11 +406,10 @@ process.on('SIGTERM', handle);
hanging in an endless loop, since listeners attached using `process.on()` are
called asynchronously and therefore unable to correct the underlying problem.
*Note*: Windows does not support sending signals, but Node.js offers some
emulation with [`process.kill()`][], and [`subprocess.kill()`][]. Sending
signal `0` can be used to test for the existence of a process. Sending `SIGINT`,
`SIGTERM`, and `SIGKILL` cause the unconditional termination of the target
process.
Windows does not support sending signals, but Node.js offers some emulation
with [`process.kill()`][], and [`subprocess.kill()`][]. Sending signal `0` can
be used to test for the existence of a process. Sending `SIGINT`, `SIGTERM`,
and `SIGKILL` cause the unconditional termination of the target process.
## process.abort()
<!-- YAML
@ -567,9 +566,9 @@ An example of the possible output looks like:
}
```
*Note*: The `process.config` property is **not** read-only and there are
existing modules in the ecosystem that are known to extend, modify, or entirely
replace the value of `process.config`.
The `process.config` property is **not** read-only and there are existing
modules in the ecosystem that are known to extend, modify, or entirely replace
the value of `process.config`.
## process.connected
<!-- YAML
@ -674,9 +673,9 @@ If there are specific reasons to use `process.dlopen()` (for instance,
to specify dlopen flags), it's often useful to use [`require.resolve()`][]
to look up the module's path.
*Note*: An important drawback when calling `process.dlopen()` is that the
`module` instance must be passed. Functions exported by the C++ Addon will
be accessible via `module.exports`.
An important drawback when calling `process.dlopen()` is that the `module`
instance must be passed. Functions exported by the C++ Addon will be accessible
via `module.exports`.
The example below shows how to load a C++ Addon, named as `binding`,
that exports a `foo` function. All the symbols will be loaded before
@ -1057,8 +1056,8 @@ if (process.getegid) {
}
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.geteuid()
<!-- YAML
@ -1076,8 +1075,8 @@ if (process.geteuid) {
}
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.getgid()
<!-- YAML
@ -1095,9 +1094,8 @@ if (process.getgid) {
}
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.getgroups()
<!-- YAML
@ -1110,8 +1108,8 @@ The `process.getgroups()` method returns an array with the supplementary group
IDs. POSIX leaves it unspecified if the effective group ID is included but
Node.js ensures it always is.
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.getuid()
<!-- YAML
@ -1129,8 +1127,8 @@ if (process.getuid) {
}
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.hasUncaughtExceptionCaptureCallback()
<!-- YAML
@ -1202,8 +1200,8 @@ process.setgid(1000); // drop root gid
console.log(process.getgroups()); // [ 27, 30, 46, 1000 ]
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.kill(pid[, signal])
<!-- YAML
@ -1225,9 +1223,9 @@ case, a signal of `0` can be used to test for the existence of a process.
Windows platforms will throw an error if the `pid` is used to kill a process
group.
*Note*: Even though the name of this function is `process.kill()`, it is
really just a signal sender, like the `kill` system call. The signal sent may
do something other than kill the target process.
Even though the name of this function is `process.kill()`, it is really just a
signal sender, like the `kill` system call. The signal sent may do something
other than kill the target process.
For example:
@ -1244,8 +1242,8 @@ setTimeout(() => {
process.kill(process.pid, 'SIGHUP');
```
*Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start
the debugger, see [Signal Events][].
When `SIGUSR1` is received by a Node.js process, Node.js will start the
debugger, see [Signal Events][].
## process.mainModule
<!-- YAML
@ -1400,10 +1398,10 @@ function definitelyAsync(arg, cb) {
}
```
*Note*: The next tick queue is completely drained on each pass of the
event loop **before** additional I/O is processed. As a result,
recursively setting nextTick callbacks will block any I/O from
happening, just like a `while(true);` loop.
The next tick queue is completely drained on each pass of the event loop
**before** additional I/O is processed. As a result, recursively setting
nextTick callbacks will block any I/O from happening, just like a
`while(true);` loop.
## process.noDeprecation
<!-- YAML
@ -1541,8 +1539,8 @@ used to send messages to the parent process. Messages will be received as a
If Node.js was not spawned with an IPC channel, `process.send()` will be
`undefined`.
*Note*: The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.
The message goes through serialization and parsing. The resulting message might
not be the same as what is originally sent.
## process.setegid(id)
<!-- YAML
@ -1568,8 +1566,8 @@ if (process.getegid && process.setegid) {
}
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.seteuid(id)
@ -1596,8 +1594,8 @@ if (process.geteuid && process.seteuid) {
}
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.setgid(id)
<!-- YAML
@ -1623,8 +1621,8 @@ if (process.getgid && process.setgid) {
}
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.setgroups(groups)
<!-- YAML
@ -1639,8 +1637,8 @@ to have `root` or the `CAP_SETGID` capability.
The `groups` array can contain numeric group IDs, group names or both.
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.setuid(id)
<!-- YAML
@ -1664,9 +1662,8 @@ if (process.getuid && process.setuid) {
}
```
*Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android).
This function is only available on POSIX platforms (i.e. not Windows or
Android).
## process.setUncaughtExceptionCaptureCallback(fn)
<!-- YAML
@ -1688,8 +1685,8 @@ To unset the capture function, `process.setUncaughtExceptionCapture(null)`
may be used. Calling this method with a non-`null` argument while another
capture function is set will throw an error.
*Note*: Using this function is mutually exclusive with using the
deprecated [`domain`][] built-in module.
Using this function is mutually exclusive with using the deprecated
[`domain`][] built-in module.
## process.stderr
@ -1700,8 +1697,8 @@ The `process.stderr` property returns a stream connected to
stream) unless fd `2` refers to a file, in which case it is
a [Writable][] stream.
*Note*: `process.stderr` differs from other Node.js streams in important ways,
see [note on process I/O][] for more information.
`process.stderr` differs from other Node.js streams in important ways, see
[note on process I/O][] for more information.
## process.stdin
@ -1733,7 +1730,7 @@ As a [Duplex][] stream, `process.stdin` can also be used in "old" mode that
is compatible with scripts written for Node.js prior to v0.10.
For more information see [Stream compatibility][].
*Note*: In "old" streams mode the `stdin` stream is paused by default, so one
In "old" streams mode the `stdin` stream is paused by default, so one
must call `process.stdin.resume()` to read from it. Note also that calling
`process.stdin.resume()` itself would switch stream to "old" mode.
@ -1752,8 +1749,8 @@ For example, to copy process.stdin to process.stdout:
process.stdin.pipe(process.stdout);
```
*Note*: `process.stdout` differs from other Node.js streams in important ways,
see [note on process I/O][] for more information.
`process.stdout` differs from other Node.js streams in important ways, see
[note on process I/O][] for more information.
### A note on process I/O
@ -1828,14 +1825,14 @@ The `process.title` property returns the current process title (i.e. returns
the current value of `ps`). Assigning a new value to `process.title` modifies
the current value of `ps`.
*Note*: When a new value is assigned, different platforms will impose
different maximum length restrictions on the title. Usually such restrictions
are quite limited. For instance, on Linux and macOS, `process.title` is limited
to the size of the binary name plus the length of the command line arguments
because setting the `process.title` overwrites the `argv` memory of the
process. Node.js v0.8 allowed for longer process title strings by also
overwriting the `environ` memory but that was potentially insecure and
confusing in some (rather obscure) cases.
When a new value is assigned, different platforms will impose different maximum
length restrictions on the title. Usually such restrictions are quite limited.
For instance, on Linux and macOS, `process.title` is limited to the size of the
binary name plus the length of the command line arguments because setting the
`process.title` overwrites the `argv` memory of the process. Node.js v0.8
allowed for longer process title strings by also overwriting the `environ`
memory but that was potentially insecure and confusing in some (rather obscure)
cases.
## process.traceDeprecation
<!-- YAML
@ -1881,8 +1878,8 @@ added: v0.5.0
The `process.uptime()` method returns the number of seconds the current Node.js
process has been running.
*Note*: The return value includes fractions of a second. Use `Math.floor()`
to get whole seconds.
The return value includes fractions of a second. Use `Math.floor()` to get whole
seconds.
## process.version
<!-- YAML

2
doc/api/punycode.md
View File

@ -33,7 +33,7 @@ to `'example.com'`) is represented by Punycode as the ASCII string
The `punycode` module provides a simple implementation of the Punycode standard.
*Note*: The `punycode` module is a third-party dependency used by Node.js and
The `punycode` module is a third-party dependency used by Node.js and
made available to developers as a convenience. Fixes or other modifications to
the module must be directed to the [Punycode.js][] project.

2
doc/api/querystring.md
View File

@ -69,7 +69,7 @@ For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into:
}
```
*Note*: The object returned by the `querystring.parse()` method _does not_
The object returned by the `querystring.parse()` method _does not_
prototypically inherit from the JavaScript `Object`. This means that typical
`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others
are not defined and *will not work*.

22
doc/api/readline.md
View File

@ -29,9 +29,9 @@ rl.question('What do you think of Node.js? ', (answer) => {
});
```
*Note*: Once this code is invoked, the Node.js application will not
terminate until the `readline.Interface` is closed because the interface
waits for data to be received on the `input` stream.
Once this code is invoked, the Node.js application will not terminate until the
`readline.Interface` is closed because the interface waits for data to be
received on the `input` stream.
## Class: Interface
<!-- YAML
@ -142,7 +142,7 @@ rl.on('SIGCONT', () => {
});
```
*Note*: The `'SIGCONT'` event is _not_ supported on Windows.
The `'SIGCONT'` event is _not_ supported on Windows.
### Event: 'SIGINT'
<!-- YAML
@ -194,7 +194,7 @@ rl.on('SIGTSTP', () => {
});
```
*Note*: The `'SIGTSTP'` event is _not_ supported on Windows.
The `'SIGTSTP'` event is _not_ supported on Windows.
### rl.close()
<!-- YAML
@ -262,8 +262,8 @@ rl.question('What is your favorite food? ', (answer) => {
});
```
*Note*: The `callback` function passed to `rl.question()` does not follow the
typical pattern of accepting an `Error` object or `null` as the first argument.
The `callback` function passed to `rl.question()` does not follow the typical
pattern of accepting an `Error` object or `null` as the first argument.
The `callback` is called with the provided answer as the only argument.
### rl.resume()
@ -315,8 +315,8 @@ rl.write('Delete this!');
rl.write(null, { ctrl: true, name: 'u' });
```
*Note*: The `rl.write()` method will write the data to the `readline`
Interface's `input` *as if it were provided by the user*.
The `rl.write()` method will write the data to the `readline` Interface's
`input` *as if it were provided by the user*.
## readline.clearLine(stream, dir)
<!-- YAML
@ -467,8 +467,8 @@ autocompletion is disabled when copy-pasted input is detected.
If the `stream` is a [TTY][], then it must be in raw mode.
*Note*: This is automatically called by any readline instance on its `input`
if the `input` is a terminal. Closing the `readline` instance does not stop
This is automatically called by any readline instance on its `input` if the
`input` is a terminal. Closing the `readline` instance does not stop
the `input` from emitting `'keypress'` events.
```js

143
doc/api/stream.md
View File

@ -188,8 +188,8 @@ Examples of [Writable][] streams include:
* [child process stdin][]
* [`process.stdout`][], [`process.stderr`][]
*Note*: Some of these examples are actually [Duplex][] streams that implement
the [Writable][] interface.
Some of these examples are actually [Duplex][] streams that implement the
[Writable][] interface.
All [Writable][] streams implement the interface defined by the
`stream.Writable` class.
@ -270,7 +270,7 @@ added: v0.9.4
The `'error'` event is emitted if an error occurred while writing or piping
data. The listener callback is passed a single `Error` argument when called.
*Note*: The stream is not closed when the `'error'` event is emitted.
The stream is not closed when the `'error'` event is emitted.
##### Event: 'finish'
<!-- YAML
@ -589,15 +589,14 @@ until a mechanism for either consuming or ignoring that data is provided. If
the consuming mechanism is disabled or taken away, the Readable will *attempt*
to stop generating the data.
*Note*: For backwards compatibility reasons, removing [`'data'`][] event
handlers will **not** automatically pause the stream. Also, if there are piped
destinations, then calling [`stream.pause()`][stream-pause] will not guarantee
that the stream will *remain* paused once those destinations drain and ask for
more data.
For backwards compatibility reasons, removing [`'data'`][] event handlers will
**not** automatically pause the stream. Also, if there are piped destinations,
then calling [`stream.pause()`][stream-pause] will not guarantee that the
stream will *remain* paused once those destinations drain and ask for more data.
*Note*: If a [Readable][] is switched into flowing mode and there are no
consumers available to handle the data, that data will be lost. This can occur,
for instance, when the `readable.resume()` method is called without a listener
If a [Readable][] is switched into flowing mode and there are no consumers
available to handle the data, that data will be lost. This can occur, for
instance, when the `readable.resume()` method is called without a listener
attached to the `'data'` event, or when a `'data'` event handler is removed
from the stream.
@ -715,10 +714,10 @@ added: v0.9.4
The `'end'` event is emitted when there is no more data to be consumed from
the stream.
*Note*: The `'end'` event **will not be emitted** unless the data is
completely consumed. This can be accomplished by switching the stream into
flowing mode, or by calling [`stream.read()`][stream-read] repeatedly until
all data has been consumed.
The `'end'` event **will not be emitted** unless the data is completely
consumed. This can be accomplished by switching the stream into flowing mode,
or by calling [`stream.read()`][stream-read] repeatedly until all data has been
consumed.
```js
const readable = getReadableStreamSomehow();
@ -793,9 +792,9 @@ readable: null
end
```
*Note*: In general, the `readable.pipe()` and `'data'` event mechanisms are
easier to understand than the `'readable'` event.
However, handling `'readable'` might result in increased throughput.
In general, the `readable.pipe()` and `'data'` event mechanisms are easier to
understand than the `'readable'` event. However, handling `'readable'` might
result in increased throughput.
##### readable.isPaused()
<!-- YAML
@ -897,9 +896,8 @@ processing, the Writable destination *is not closed* automatically. If an
error occurs, it will be necessary to *manually* close each stream in order
to prevent memory leaks.
*Note*: The [`process.stderr`][] and [`process.stdout`][] Writable streams are
never closed until the Node.js process exits, regardless of the specified
options.
The [`process.stderr`][] and [`process.stdout`][] Writable streams are never
closed until the Node.js process exits, regardless of the specified options.
##### readable.readableHighWaterMark
<!-- YAML
@ -953,11 +951,11 @@ A Readable stream in object mode will always return a single item from
a call to [`readable.read(size)`][stream-read], regardless of the value of the
`size` argument.
*Note*: If the `readable.read()` method returns a chunk of data, a `'data'`
event will also be emitted.
If the `readable.read()` method returns a chunk of data, a `'data'` event will
also be emitted.
*Note*: Calling [`stream.read([size])`][stream-read] after the [`'end'`][]
event has been emitted will return `null`. No runtime error will be raised.
Calling [`stream.read([size])`][stream-read] after the [`'end'`][] event has
been emitted will return `null`. No runtime error will be raised.
##### readable.readableLength
<!-- YAML
@ -1070,8 +1068,8 @@ buffer. This is useful in certain situations where a stream is being consumed by
code that needs to "un-consume" some amount of data that it has optimistically
pulled out of the source, so that the data can be passed on to some other party.
*Note*: The `stream.unshift(chunk)` method cannot be called after the
[`'end'`][] event has been emitted or a runtime error will be thrown.
The `stream.unshift(chunk)` method cannot be called after the [`'end'`][] event
has been emitted or a runtime error will be thrown.
Developers using `stream.unshift()` often should consider switching to
use of a [Transform][] stream instead. See the [API for Stream Implementers][]
@ -1113,14 +1111,14 @@ function parseHeader(stream, callback) {
}
```
*Note*: Unlike [`stream.push(chunk)`][stream-push], `stream.unshift(chunk)`
will not end the reading process by resetting the internal reading state of the
stream. This can cause unexpected results if `readable.unshift()` is called
during a read (i.e. from within a [`stream._read()`][stream-_read]
implementation on a custom stream). Following the call to `readable.unshift()`
with an immediate [`stream.push('')`][stream-push] will reset the reading state
appropriately, however it is best to simply avoid calling `readable.unshift()`
while in the process of performing a read.
Unlike [`stream.push(chunk)`][stream-push], `stream.unshift(chunk)` will not
end the reading process by resetting the internal reading state of the stream.
This can cause unexpected results if `readable.unshift()` is called during a
read (i.e. from within a [`stream._read()`][stream-_read] implementation on a
custom stream). Following the call to `readable.unshift()` with an immediate
[`stream.push('')`][stream-push] will reset the reading state appropriately,
however it is best to simply avoid calling `readable.unshift()` while in the
process of performing a read.
##### readable.wrap(stream)
<!-- YAML
@ -1329,10 +1327,10 @@ on the type of stream being created, as detailed in the chart below:
</tr>
</table>
*Note*: The implementation code for a stream should *never* call the "public"
methods of a stream that are intended for use by consumers (as described in
the [API for Stream Consumers][] section). Doing so may lead to adverse
side effects in application code consuming the stream.
The implementation code for a stream should *never* call the "public" methods
of a stream that are intended for use by consumers (as described in the
[API for Stream Consumers][] section). Doing so may lead to adverse side effects
in application code consuming the stream.
### Simplified Construction
<!-- YAML
@ -1445,12 +1443,12 @@ All Writable stream implementations must provide a
[`writable._write()`][stream-_write] method to send data to the underlying
resource.
*Note*: [Transform][] streams provide their own implementation of the
[Transform][] streams provide their own implementation of the
[`writable._write()`][stream-_write].
*Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called by the internal Writable
class methods only.
This function MUST NOT be called by application code directly. It should be
implemented by child classes, and called by the internal Writable class methods
only.
The `callback` method must be called to signal either that the write completed
successfully or failed with an error. The first argument passed to the
@ -1482,9 +1480,9 @@ user programs.
* `callback` {Function} A callback function (optionally with an error
argument) to be invoked when processing is complete for the supplied chunks.
*Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called by the internal Writable
class methods only.
This function MUST NOT be called by application code directly. It should be
implemented by child classes, and called by the internal Writable class methods
only.
The `writable._writev()` method may be implemented in addition to
`writable._write()` in stream implementations that are capable of processing
@ -1688,9 +1686,9 @@ changes:
* `size` {number} Number of bytes to read asynchronously
*Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called by the internal Readable
class methods only.
This function MUST NOT be called by application code directly. It should be
implemented by child classes, and called by the internal Readable class methods
only.
All Readable stream implementations must provide an implementation of the
`readable._read()` method to fetch data from the underlying resource.
@ -1702,10 +1700,10 @@ from the resource and pushing data until `readable.push()` returns `false`. Only
when `_read()` is called again after it has stopped should it resume pushing
additional data onto the queue.
*Note*: Once the `readable._read()` method has been called, it will not be
called again until the [`readable.push()`][stream-push] method is called.
`readable._read()` is guaranteed to be called only once within a
synchronous execution, i.e. a microtick.
Once the `readable._read()` method has been called, it will not be called again
until the [`readable.push()`][stream-push] method is called. `readable._read()`
is guaranteed to be called only once within a synchronous execution, i.e. a
microtick.
The `size` argument is advisory. For implementations where a "read" is a
single operation that returns data can use the `size` argument to determine how
@ -1794,7 +1792,8 @@ class SourceWrapper extends Readable {
}
}
```
*Note*: The `readable.push()` method is intended be called only by Readable
The `readable.push()` method is intended be called only by Readable
Implementers, and only from within the `readable._read()` method.
#### Errors While Reading
@ -1860,10 +1859,10 @@ Because JavaScript does not have support for multiple inheritance, the
`stream.Duplex` class is extended to implement a [Duplex][] stream (as opposed
to extending the `stream.Readable` *and* `stream.Writable` classes).
*Note*: The `stream.Duplex` class prototypically inherits from
`stream.Readable` and parasitically from `stream.Writable`, but `instanceof`
will work properly for both base classes due to overriding
[`Symbol.hasInstance`][] on `stream.Writable`.
The `stream.Duplex` class prototypically inherits from `stream.Readable` and
parasitically from `stream.Writable`, but `instanceof` will work properly for
both base classes due to overriding [`Symbol.hasInstance`][] on
`stream.Writable`.
Custom Duplex streams *must* call the `new stream.Duplex([options])`
constructor and implement *both* the `readable._read()` and
@ -2023,11 +2022,11 @@ A [Transform][] stream is a [Duplex][] stream where the output is computed
in some way from the input. Examples include [zlib][] streams or [crypto][]
streams that compress, encrypt, or decrypt data.
*Note*: There is no requirement that the output be the same size as the input,
the same number of chunks, or arrive at the same time. For example, a
Hash stream will only ever have a single chunk of output which is
provided when the input is ended. A `zlib` stream will produce output
that is either much smaller or much larger than its input.
There is no requirement that the output be the same size as the input, the same
number of chunks, or arrive at the same time. For example, a Hash stream will
only ever have a single chunk of output which is provided when the input is
ended. A `zlib` stream will produce output that is either much smaller or much
larger than its input.
The `stream.Transform` class is extended to implement a [Transform][] stream.
@ -2037,9 +2036,9 @@ methods. Custom Transform implementations *must* implement the
[`transform._transform()`][stream-_transform] method and *may* also implement
the [`transform._flush()`][stream-_flush] method.
*Note*: Care must be taken when using Transform streams in that data written
to the stream can cause the Writable side of the stream to become paused if
the output on the Readable side is not consumed.
Care must be taken when using Transform streams in that data written to the
stream can cause the Writable side of the stream to become paused if the output
on the Readable side is not consumed.
#### new stream.Transform([options])
@ -2103,9 +2102,9 @@ after all data has been output, which occurs after the callback in
* `callback` {Function} A callback function (optionally with an error
argument and data) to be called when remaining data has been flushed.
*Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called by the internal Readable
class methods only.
This function MUST NOT be called by application code directly. It should be
implemented by child classes, and called by the internal Readable class methods
only.
In some cases, a transform operation may need to emit an additional bit of
data at the end of the stream. For example, a `zlib` compression stream will
@ -2138,9 +2137,9 @@ user programs.
argument and data) to be called after the supplied `chunk` has been
processed.
*Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called by the internal Readable
class methods only.
This function MUST NOT be called by application code directly. It should be
implemented by child classes, and called by the internal Readable class methods
only.
All Transform stream implementations must provide a `_transform()`
method to accept input and produce output. The `transform._transform()`

20
doc/api/timers.md
View File

@ -32,9 +32,8 @@ When called, requests that the Node.js event loop *not* exit so long as the
`Immediate` is active. Calling `immediate.ref()` multiple times will have no
effect.
*Note*: By default, all `Immediate` objects are "ref'd", making it normally
unnecessary to call `immediate.ref()` unless `immediate.unref()` had been called
previously.
By default, all `Immediate` objects are "ref'd", making it normally unnecessary
to call `immediate.ref()` unless `immediate.unref()` had been called previously.
Returns a reference to the `Immediate`.
@ -70,9 +69,8 @@ added: v0.9.1
When called, requests that the Node.js event loop *not* exit so long as the
`Timeout` is active. Calling `timeout.ref()` multiple times will have no effect.
*Note*: By default, all `Timeout` objects are "ref'd", making it normally
unnecessary to call `timeout.ref()` unless `timeout.unref()` had been called
previously.
By default, all `Timeout` objects are "ref'd", making it normally unnecessary
to call `timeout.ref()` unless `timeout.unref()` had been called previously.
Returns a reference to the `Timeout`.
@ -86,8 +84,8 @@ to remain active. If there is no other activity keeping the event loop running,
the process may exit before the `Timeout` object's callback is invoked. Calling
`timeout.unref()` multiple times will have no effect.
*Note*: Calling `timeout.unref()` creates an internal timer that will wake the
Node.js event loop. Creating too many of these can adversely impact performance
Calling `timeout.unref()` creates an internal timer that will wake the Node.js
event loop. Creating too many of these can adversely impact performance
of the Node.js application.
Returns a reference to the `Timeout`.
@ -119,7 +117,7 @@ next event loop iteration.
If `callback` is not a function, a [`TypeError`][] will be thrown.
*Note*: This method has a custom variant for promises that is available using
This method has a custom variant for promises that is available using
[`util.promisify()`][]:
```js
@ -176,12 +174,12 @@ Node.js makes no guarantees about the exact timing of when callbacks will fire,
nor of their ordering. The callback will be called as close as possible to the
time specified.
*Note*: When `delay` is larger than `2147483647` or less than `1`, the `delay`
When `delay` is larger than `2147483647` or less than `1`, the `delay`
will be set to `1`.
If `callback` is not a function, a [`TypeError`][] will be thrown.
*Note*: This method has a custom variant for promises that is available using
This method has a custom variant for promises that is available using
[`util.promisify()`][]:
```js

84
doc/api/tls.md
View File

@ -117,7 +117,7 @@ handshake extensions:
* SNI - Allows the use of one TLS server for multiple hostnames with different
SSL certificates.
*Note*: Use of ALPN is recommended over NPN. The NPN extension has never been
Use of ALPN is recommended over NPN. The NPN extension has never been
formally defined or documented and generally not recommended for use.
### Client-initiated renegotiation attack mitigation
@ -138,7 +138,7 @@ threshold is exceeded. The limits are configurable:
* `tls.CLIENT_RENEG_WINDOW` {number} Specifies the time renegotiation window
in seconds. Defaults to `600` (10 minutes).
*Note*: The default renegotiation limits should not be modified without a full
The default renegotiation limits should not be modified without a full
understanding of the implications and risks.
To test the renegotiation limits on a server, connect to it using the OpenSSL
@ -189,7 +189,7 @@ in [`tls.createServer()`], [`tls.connect()`], and when creating new
Consult [OpenSSL cipher list format documentation][] for details on the format.
*Note*: The default cipher suite included within Node.js has been carefully
The default cipher suite included within Node.js has been carefully
selected to reflect current security best practices and risk mitigation.
Changing the default cipher suite can have a significant impact on the security
of an application. The `--tls-cipher-list` switch and `ciphers` option should by
@ -230,8 +230,8 @@ three arguments when called:
* `callback` {Function} A callback function taking no arguments that must be
invoked in order for data to be sent or received over the secure connection.
*Note*: Listening for this event will have an effect only on connections
established after the addition of the event listener.
Listening for this event will have an effect only on connections established
after the addition of the event listener.
### Event: 'OCSPRequest'
<!-- YAML
@ -271,14 +271,14 @@ The typical flow of an OCSP Request is as follows:
5. Client validates the response and either destroys the socket or performs a
handshake.
*Note*: The `issuer` can be `null` if the certificate is either self-signed or
the issuer is not in the root certificates list. (An issuer may be provided
The `issuer` can be `null` if the certificate is either self-signed or the
issuer is not in the root certificates list. (An issuer may be provided
via the `ca` option when establishing the TLS connection.)
*Note*: Listening for this event will have an effect only on connections
established after the addition of the event listener.
Listening for this event will have an effect only on connections established
after the addition of the event listener.
*Note*: An npm module like [asn1.js] may be used to parse the certificates.
An npm module like [asn1.js] may be used to parse the certificates.
### Event: 'resumeSession'
<!-- YAML
@ -299,8 +299,8 @@ the session cannot be resumed (i.e., doesn't exist in storage) the callback may
be invoked as `callback(null, null)`. Calling `callback(err)` will terminate the
incoming connection and destroy the socket.
*Note*: Listening for this event will have an effect only on connections
established after the addition of the event listener.
Listening for this event will have an effect only on connections established
after the addition of the event listener.
The following illustrates resuming a TLS session:
@ -423,13 +423,12 @@ added: v3.0.0
Updates the keys for encryption/decryption of the [TLS Session Tickets][].
*Note*: The key's `Buffer` should be 48 bytes long. See `ticketKeys` option in
The key's `Buffer` should be 48 bytes long. See `ticketKeys` option in
[tls.createServer](#tls_tls_createserver_options_secureconnectionlistener) for
more information on how it is used.
*Note*: Changes to the ticket keys are effective only for future server
connections. Existing or currently pending server connections will use the
previous keys.
Changes to the ticket keys are effective only for future server connections.
Existing or currently pending server connections will use the previous keys.
## Class: tls.TLSSocket
@ -442,7 +441,7 @@ encryption of written data and all required TLS negotiation.
Instances of `tls.TLSSocket` implement the duplex [Stream][] interface.
*Note*: Methods that return TLS connection metadata (e.g.
Methods that return TLS connection metadata (e.g.
[`tls.TLSSocket.getPeerCertificate()`][] will only return data while the
connection is open.
@ -664,8 +663,8 @@ added: v0.11.4
Returns the TLS session ticket or `undefined` if no session was negotiated.
*Note*: This only works with client TLS sockets. Useful only for debugging,
for session reuse provide `session` option to [`tls.connect()`][].
This only works with client TLS sockets. Useful only for debugging, for session
reuse provide `session` option to [`tls.connect()`][].
### tlsSocket.localAddress
<!-- YAML
@ -721,11 +720,11 @@ The `tlsSocket.renegotiate()` method initiates a TLS renegotiation process.
Upon completion, the `callback` function will be passed a single argument
that is either an `Error` (if the request failed) or `null`.
*Note*: This method can be used to request a peer's certificate after the
secure connection has been established.
This method can be used to request a peer's certificate after the secure
connection has been established.
*Note*: When running as the server, the socket will be destroyed with an error
after `handshakeTimeout` timeout.
When running as the server, the socket will be destroyed with an error after
`handshakeTimeout` timeout.
### tlsSocket.setMaxSendFragment(size)
<!-- YAML
@ -759,15 +758,16 @@ Verifies the certificate `cert` is issued to host `host`.
Returns {Error} object, populating it with the reason, host, and cert on
failure. On success, returns {undefined}.
*Note*: This function can be overwritten by providing alternative function
as part of the `options.checkServerIdentity` option passed to `tls.connect()`.
The overwriting function can call `tls.checkServerIdentity()` of course, to augment
This function can be overwritten by providing alternative function as part of
the `options.checkServerIdentity` option passed to `tls.connect()`. The
overwriting function can call `tls.checkServerIdentity()` of course, to augment
the checks done with additional verification.
*Note*: This function is only called if the certificate passed all other checks, such as
This function is only called if the certificate passed all other checks, such as
being issued by trusted CA (`options.ca`).
The cert object contains the parsed certificate and will have a structure similar to:
The cert object contains the parsed certificate and will have a structure
similar to:
```text
{ subject:
@ -937,8 +937,7 @@ added: v0.11.3
Same as [`tls.connect()`][] except that `path` can be provided
as an argument instead of an option.
*Note*: A path option, if specified, will take precedence over the path
argument.
A path option, if specified, will take precedence over the path argument.
## tls.connect(port[, host][, options][, callback])
<!-- YAML
@ -953,8 +952,8 @@ added: v0.11.3
Same as [`tls.connect()`][] except that `port` and `host` can be provided
as arguments instead of options.
*Note*: A port or host option, if specified, will take precedence over any
port or host argument.
A port or host option, if specified, will take precedence over any port or host
argument.
## tls.createSecureContext(options)
@ -1052,15 +1051,12 @@ changes:
* `sessionIdContext` {string} Optional opaque identifier used by servers to
ensure session state is not shared between applications. Unused by clients.
*Note*:
[`tls.createServer()`][] sets the default value of the `honorCipherOrder` option
to `true`, other APIs that create secure contexts leave it unset.
* [`tls.createServer()`][] sets the default value of the
`honorCipherOrder` option to `true`, other APIs that create secure contexts
leave it unset.
* [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value
generated from `process.argv` as the default value of the `sessionIdContext`
option, other APIs that create secure contexts have no default value.
[`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value generated
from `process.argv` as the default value of the `sessionIdContext` option, other
APIs that create secure contexts have no default value.
The `tls.createSecureContext()` method creates a credentials object.
@ -1137,8 +1133,8 @@ changes:
Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is
automatically set as a listener for the [`'secureConnection'`][] event.
*Note*: The `ticketKeys` options is automatically shared between `cluster`
module workers.
The `ticketKeys` options is automatically shared between `cluster` module
workers.
The following illustrates a simple echo server:
@ -1314,9 +1310,9 @@ stream.
`tls.createSecurePair()` returns a `tls.SecurePair` object with `cleartext` and
`encrypted` stream properties.
*Note*: `cleartext` has the same API as [`tls.TLSSocket`][].
Using `cleartext` has the same API as [`tls.TLSSocket`][].
*Note*: The `tls.createSecurePair()` method is now deprecated in favor of
The `tls.createSecurePair()` method is now deprecated in favor of
`tls.TLSSocket()`. For example, the code:
```js

18
doc/api/url.md
View File

@ -21,8 +21,8 @@ The `url` module provides two APIs for working with URLs: a legacy API that is
Node.js specific, and a newer API that implements the same
[WHATWG URL Standard][] used by web browsers.
*Note*: While the Legacy API has not been deprecated, it is maintained solely
for backwards compatibility with existing applications. New application code
While the Legacy API has not been deprecated, it is maintained solely for
backwards compatibility with existing applications. New application code
should use the WHATWG API.
A comparison between the WHATWG and Legacy APIs is provided below. Above the URL
@ -30,7 +30,7 @@ A comparison between the WHATWG and Legacy APIs is provided below. Above the URL
an object returned by the legacy `url.parse()` are shown. Below it are
properties of a WHATWG `URL` object.
*Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not
WHATWG URL's `origin` property includes `protocol` and `host`, but not
`username` or `password`.
```txt
@ -84,7 +84,7 @@ Browser-compatible `URL` class, implemented by following the WHATWG URL
Standard. [Examples of parsed URLs][] may be found in the Standard itself.
The `URL` class is also available on the global object.
*Note*: In accordance with browser conventions, all properties of `URL` objects
In accordance with browser conventions, all properties of `URL` objects
are implemented as getters and setters on the class prototype, rather than as
data properties on the object itself. Thus, unlike [legacy urlObject][]s, using
the `delete` keyword on any properties of `URL` objects (e.g. `delete
@ -122,8 +122,8 @@ const myURL = new URL('https://你好你好');
// https://xn--6qqa088eba/
```
*Note*: This feature is only available if the `node` executable was compiled
with [ICU][] enabled. If not, the domain names are passed through unchanged.
This feature is only available if the `node` executable was compiled with
[ICU][] enabled. If not, the domain names are passed through unchanged.
#### url.hash
@ -515,9 +515,9 @@ added: v7.10.0
Instantiate a new `URLSearchParams` object with a query hash map. The key and
value of each property of `obj` are always coerced to strings.
*Note*: Unlike [`querystring`][] module, duplicate keys in the form of array
values are not allowed. Arrays are stringified using [`array.toString()`][],
which simply joins all array elements with commas.
Unlike [`querystring`][] module, duplicate keys in the form of array values are
not allowed. Arrays are stringified using [`array.toString()`][], which simply
joins all array elements with commas.
```js
const params = new URLSearchParams({

12
doc/api/util.md
View File

@ -48,13 +48,11 @@ Will print:
hello world
```
*Note*:
* The callback is executed asynchronously, and will have a limited stack trace.
The callback is executed asynchronously, and will have a limited stack trace.
If the callback throws, the process will emit an [`'uncaughtException'`][]
event, and if not handled will exit.
* Since `null` has a special meaning as the first argument to a callback, if a
Since `null` has a special meaning as the first argument to a callback, if a
wrapped function rejects a `Promise` with a falsy value as a reason, the value
is wrapped in an `Error` with the original value stored in a field named
`reason`.
@ -285,8 +283,8 @@ changes:
description: The `constructor` parameter can refer to an ES6 class now.
-->
*Note*: Usage of `util.inherits()` is discouraged. Please use the ES6 `class`
and `extends` keywords to get language level inheritance support. Also note
Usage of `util.inherits()` is discouraged. Please use the ES6 `class` and
`extends` keywords to get language level inheritance support. Also note
that the two styles are [semantically incompatible][].
* `constructor` {Function}
@ -812,7 +810,7 @@ with ICU and using the full ICU data (see [Internationalization][]).
| `'shift_jis'` | `'csshiftjis'`, `'ms932'`, `'ms_kanji'`, `'shift-jis'`, `'sjis'`, `'windows-31j'`, `'x-sjis'` |
| `'euc-kr'` | `'cseuckr'`, `'csksc56011987'`, `'iso-ir-149'`, `'korean'`, `'ks_c_5601-1987'`, `'ks_c_5601-1989'`, `'ksc5601'`, `'ksc_5601'`, `'windows-949'` |
*Note*: The `'iso-8859-16'` encoding listed in the [WHATWG Encoding Standard][]
The `'iso-8859-16'` encoding listed in the [WHATWG Encoding Standard][]
is not supported.
### new TextDecoder([encoding[, options]])

4
doc/api/v8.md
View File

@ -9,7 +9,7 @@ built into the Node.js binary. It can be accessed using:
const v8 = require('v8');
```
*Note*: The APIs and implementation are subject to change at any time.
The APIs and implementation are subject to change at any time.
## v8.cachedDataVersionTag()
<!-- YAML
@ -165,7 +165,7 @@ The serialization API provides means of serializing JavaScript values in a way
that is compatible with the [HTML structured clone algorithm][].
The format is backward-compatible (i.e. safe to store to disk).
*Note*: This API is under development, and changes (including incompatible
This API is under development, and changes (including incompatible
changes to the API or wire format) may occur until this warning is removed.
### v8.serialize(value)

18
doc/api/vm.md
View File

@ -40,8 +40,8 @@ console.log(sandbox.y); // 17
console.log(x); // 1; y is not defined.
```
*Note*: The vm module is not a security mechanism.
**Do not use it to run untrusted code**.
**The vm module is not a security mechanism. Do not use it to run untrusted
code**.
## Class: vm.Module
<!-- YAML
@ -68,7 +68,7 @@ Using a `vm.Module` object requires four distinct steps: creation/parsing,
linking, instantiation, and evaluation. These four steps are illustrated in the
following example.
*Note*: This implementation lies at a lower level than the [ECMAScript Module
This implementation lies at a lower level than the [ECMAScript Module
loader][]. There is also currently no way to interact with the Loader, though
support is planned.
@ -191,7 +191,7 @@ If the `module.status` is `'errored'`, this property contains the exception thro
by the module during evaluation. If the status is anything else, accessing this
property will result in a thrown exception.
*Note*: `undefined` cannot be used for cases where there is not a thrown
The value `undefined` cannot be used for cases where there is not a thrown
exception due to possible ambiguity with `throw undefined;`.
Corresponds to the [[EvaluationError]] field of [Source Text Module Record][]s
@ -465,9 +465,9 @@ console.log(util.inspect(sandbox));
// { animal: 'cat', count: 12, name: 'kitty' }
```
*Note*: Using the `timeout` or `breakOnSigint` options will result in new
event loops and corresponding threads being started, which have a non-zero
performance overhead.
Using the `timeout` or `breakOnSigint` options will result in new event loops
and corresponding threads being started, which have a non-zero performance
overhead.
### script.runInNewContext([sandbox[, options]])
<!-- YAML
@ -803,8 +803,8 @@ const code = `
vm.runInThisContext(code)(require);
```
*Note*: The `require()` in the above case shares the state with the context it
is passed from. This may introduce risks when untrusted code is executed, e.g.
The `require()` in the above case shares the state with the context it is
passed from. This may introduce risks when untrusted code is executed, e.g.
altering objects in the context in unwanted ways.
## What does it mean to "contextify" an object?

17
doc/api/zlib.md
View File

@ -63,10 +63,10 @@ the compression encodings accepted by the client. The [`Content-Encoding`][]
header is used to identify the compression encodings actually applied to a
message.
*Note*: the examples given below are drastically simplified to show
the basic concept. Using `zlib` encoding can be expensive, and the results
ought to be cached. See [Memory Usage Tuning][] for more information
on the speed/memory/compression tradeoffs involved in `zlib` usage.
The examples given below are drastically simplified to show the basic concept.
Using `zlib` encoding can be expensive, and the results ought to be cached.
See [Memory Usage Tuning][] for more information on the speed/memory/compression
tradeoffs involved in `zlib` usage.
```js
// client request example
@ -238,10 +238,9 @@ not surprising. This section is taken almost directly from the
[zlib documentation][]. See <https://zlib.net/manual.html#Constants> for more
details.
*Note*: Previously, the constants were available directly from
`require('zlib')`, for instance `zlib.Z_NO_FLUSH`. Accessing the constants
directly from the module is currently still possible but should be considered
deprecated.
Previously, the constants were available directly from `require('zlib')`, for
instance `zlib.Z_NO_FLUSH`. Accessing the constants directly from the module is
currently still possible but is deprecated.
Allowed flush values.
@ -468,7 +467,7 @@ added: v0.5.8
Creates and returns a new [DeflateRaw][] object with the given [options][].
*Note*: An upgrade of zlib from 1.2.8 to 1.2.11 changed behavior when windowBits
An upgrade of zlib from 1.2.8 to 1.2.11 changed behavior when windowBits
is set to 8 for raw deflate streams. zlib would automatically set windowBits
to 9 if was initially set to 8. Newer versions of zlib will throw an exception,
so Node.js restored the original behavior of upgrading a value of 8 to 9,