diff options
| -rw-r--r-- | doc/api/addons.md | 2 | ||||
| -rw-r--r-- | doc/api/async_hooks.md | 12 | ||||
| -rw-r--r-- | doc/api/buffer.md | 18 | ||||
| -rw-r--r-- | doc/api/child_process.md | 68 | ||||
| -rw-r--r-- | doc/api/cli.md | 40 | ||||
| -rw-r--r-- | doc/api/cluster.md | 6 | ||||
| -rw-r--r-- | doc/api/console.md | 9 | ||||
| -rw-r--r-- | doc/api/crypto.md | 22 | ||||
| -rw-r--r-- | doc/api/deprecations.md | 26 | ||||
| -rw-r--r-- | doc/api/documentation.md | 6 | ||||
| -rw-r--r-- | doc/api/errors.md | 2 | ||||
| -rw-r--r-- | doc/api/fs.md | 107 | ||||
| -rw-r--r-- | doc/api/http.md | 16 | ||||
| -rw-r--r-- | doc/api/http2.md | 97 | ||||
| -rw-r--r-- | doc/api/intl.md | 4 | ||||
| -rw-r--r-- | doc/api/modules.md | 20 | ||||
| -rw-r--r-- | doc/api/n-api.md | 46 | ||||
| -rw-r--r-- | doc/api/net.md | 21 | ||||
| -rw-r--r-- | doc/api/os.md | 18 | ||||
| -rw-r--r-- | doc/api/path.md | 6 | ||||
| -rw-r--r-- | doc/api/process.md | 127 | ||||
| -rw-r--r-- | doc/api/punycode.md | 2 | ||||
| -rw-r--r-- | doc/api/querystring.md | 2 | ||||
| -rw-r--r-- | doc/api/readline.md | 22 | ||||
| -rw-r--r-- | doc/api/stream.md | 143 | ||||
| -rw-r--r-- | doc/api/timers.md | 20 | ||||
| -rw-r--r-- | doc/api/tls.md | 84 | ||||
| -rw-r--r-- | doc/api/url.md | 18 | ||||
| -rw-r--r-- | doc/api/util.md | 12 | ||||
| -rw-r--r-- | doc/api/v8.md | 4 | ||||
| -rw-r--r-- | doc/api/vm.md | 18 | ||||
| -rw-r--r-- | doc/api/zlib.md | 17 |
32 files changed, 493 insertions, 522 deletions
diff --git a/doc/api/addons.md b/doc/api/addons.md index c6802530f6..385f64d955 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -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 diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index e0922fcd11..d854d737dc 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -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. diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 5e72e3bd96..ec2c409ba5 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -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` diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 715eb9d269..768eb91a83 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -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: diff --git a/doc/api/cli.md b/doc/api/cli.md index 6bae0a67c3..47dcd242a1 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -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 diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 3063af83bd..11be4d34d5 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -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 diff --git a/doc/api/console.md b/doc/api/console.md index 864560f8c5..473c37ea04 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -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. diff --git a/doc/api/crypto.md b/doc/api/crypto.md index a06a6d1b4e..eb6662f01f 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -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 diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index a9de845146..a5386f7bf0 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -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() diff --git a/doc/api/documentation.md b/doc/api/documentation.md index f78d7c1f40..c2413d33db 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -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 diff --git a/doc/api/errors.md b/doc/api/errors.md index d78caacd63..128a3ff68b 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -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. diff --git a/doc/api/fs.md b/doc/api/fs.md index 3aa0f86378..4c801fe358 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -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 diff --git a/doc/api/http.md b/doc/api/http.md index 341a08c5ae..0a4fe95998 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -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 diff --git a/doc/api/http2.md b/doc/api/http2.md index f1d4b1590d..083a491cca 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -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 diff --git a/doc/api/intl.md b/doc/api/intl.md index 83a9947dc2..3072e974e8 100644 --- a/doc/api/intl.md +++ b/doc/api/intl.md @@ -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()`. diff --git a/doc/api/modules.md b/doc/api/modules.md index 157ec3b6f7..be45991f1d 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -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 diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 38cf7a8842..3a954bd0d5 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -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 diff --git a/doc/api/net.md b/doc/api/net.md index b213829ffd..6e2b7386b3 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -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 diff --git a/doc/api/os.md b/doc/api/os.md index bb25c3f6cc..b5ecab0132 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -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 diff --git a/doc/api/path.md b/doc/api/path.md index eb2621bfa1..42824322b8 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -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 diff --git a/doc/api/process.md b/doc/api/process.md index fc2a450f98..400cd26a12 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -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 diff --git a/doc/api/punycode.md b/doc/api/punycode.md index 03ee3d62eb..01df2809d5 100644 --- a/doc/api/punycode.md +++ b/doc/api/punycode.md @@ -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. diff --git a/doc/api/querystring.md b/doc/api/querystring.md index 5bd4f1cce1..48412b01b9 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -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*. diff --git a/doc/api/readline.md b/doc/api/readline.md index 42d07da2d0..2e6c9cb07f 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -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 diff --git a/doc/api/stream.md b/doc/api/stream.md index 345e0d824d..023ba4d77b 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -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()` diff --git a/doc/api/timers.md b/doc/api/timers.md index 13f2dea37d..30c3200b1d 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -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 diff --git a/doc/api/tls.md b/doc/api/tls.md index ea577c2583..161ec5d963 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -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 diff --git a/doc/api/url.md b/doc/api/url.md index 42137b4ddd..c6463d75dc 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -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({ diff --git a/doc/api/util.md b/doc/api/util.md index 00100c9d5e..b5a3f51ad6 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -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]]) diff --git a/doc/api/v8.md b/doc/api/v8.md index c9d2512fdd..e4e3de78ce 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -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) diff --git a/doc/api/vm.md b/doc/api/vm.md index 8ea217da86..824cd4d403 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -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? diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 909a52d6e5..5c02c3a409 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -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, |