summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNick Schonning <nschonni@gmail.com>2019-09-06 01:42:22 -0400
committerTrivikram Kamat <16024985+trivikr@users.noreply.github.com>2019-09-09 16:45:24 -0700
commitc929b15d1d65ae88261c65e901c7dca9f110a2c5 (patch)
tree8f76e0fa29566267ba53ad0bfdef72ea72129e6d
parent6723169097759502da11c47389ffb3d650404417 (diff)
downloadandroid-node-v8-c929b15d1d65ae88261c65e901c7dca9f110a2c5.tar.gz
android-node-v8-c929b15d1d65ae88261c65e901c7dca9f110a2c5.tar.bz2
android-node-v8-c929b15d1d65ae88261c65e901c7dca9f110a2c5.zip
doc: space around lists
Address markdownlint rule MD032. Flagged a few mixed list styles. PR-URL: https://github.com/nodejs/node/pull/29467 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
-rw-r--r--COLLABORATOR_GUIDE.md4
-rw-r--r--CPP_STYLE_GUIDE.md2
-rw-r--r--doc/STYLE_GUIDE.md1
-rw-r--r--doc/api/addons.md3
-rw-r--r--doc/api/assert.md18
-rw-r--r--doc/api/console.md18
-rw-r--r--doc/api/crypto.md75
-rw-r--r--doc/api/dgram.md2
-rw-r--r--doc/api/dns.md31
-rw-r--r--doc/api/esm.md8
-rw-r--r--doc/api/events.md11
-rw-r--r--doc/api/fs.md16
-rw-r--r--doc/api/http.md1
-rw-r--r--doc/api/http2.md23
-rw-r--r--doc/api/https.md9
-rw-r--r--doc/api/n-api.md13
-rw-r--r--doc/api/net.md4
-rw-r--r--doc/api/perf_hooks.md1
-rw-r--r--doc/api/process.md2
-rw-r--r--doc/api/querystring.md1
-rw-r--r--doc/api/stream.md1
-rw-r--r--doc/api/tls.md3
-rw-r--r--doc/api/tty.md2
-rw-r--r--doc/api/util.md1
-rw-r--r--doc/api/v8.md2
-rw-r--r--doc/api/vm.md1
-rw-r--r--doc/api/worker_threads.md1
-rw-r--r--doc/api/zlib.md5
-rw-r--r--doc/changelogs/CHANGELOG_V4.md1
-rw-r--r--doc/changelogs/CHANGELOG_V5.md2
-rw-r--r--doc/guides/contributing/pull-requests.md1
-rw-r--r--doc/releases.md2
32 files changed, 249 insertions, 16 deletions
diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md
index d8e0d22fd8..b3dbd05756 100644
--- a/COLLABORATOR_GUIDE.md
+++ b/COLLABORATOR_GUIDE.md
@@ -542,9 +542,7 @@ Save the file and close the editor. When prompted, enter a new commit message
for that commit. This is an opportunity to fix commit messages.
* The commit message text must conform to the [commit message guidelines][].
-
-<a name="metadata"></a>
-* Change the original commit message to include metadata. (The
+* <a name="metadata"></a>Change the original commit message to include metadata. (The
[`git node metadata`][git-node-metadata] command can generate the metadata
for you.)
diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md
index 07733db96c..c3fe1e8407 100644
--- a/CPP_STYLE_GUIDE.md
+++ b/CPP_STYLE_GUIDE.md
@@ -36,6 +36,7 @@ features and idioms, as well as have some specific guidelines for the use of
runtime features.
Coding guidelines are based on the following guides (highest priority first):
+
1. This document
2. The [Google C++ Style Guide][]
3. The ISO [C++ Core Guidelines][]
@@ -284,6 +285,7 @@ data[0] = 12345;
[Run Time Type Information][]
Further reading:
+
* [ES.48]: Avoid casts
* [ES.49]: If you must use a cast, use a named cast
diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md
index 15ae647044..3cc162f6dc 100644
--- a/doc/STYLE_GUIDE.md
+++ b/doc/STYLE_GUIDE.md
@@ -56,6 +56,7 @@
<!--lint disable prohibited-strings remark-lint-->
* NOT OK: Javascript, Google's v8
<!-- lint enable prohibited-strings remark-lint-->
+
* Use _Node.js_ and not _Node_, _NodeJS_, or similar variants.
* When referring to the executable, _`node`_ is acceptable.
diff --git a/doc/api/addons.md b/doc/api/addons.md
index 59d708a71f..81bd8b5bac 100644
--- a/doc/api/addons.md
+++ b/doc/api/addons.md
@@ -143,6 +143,7 @@ followed by a function body.
The following three variables may be used inside the function body following an
invocation of `NODE_MODULE_INIT()`:
+
* `Local<Object> exports`,
* `Local<Value> module`, and
* `Local<Context> context`
@@ -158,6 +159,7 @@ they were created.
The context-aware addon can be structured to avoid global static data by
performing the following steps:
+
* defining a class which will hold per-addon-instance data. Such
a class should include a `v8::Persistent<v8::Object>` which will hold a weak
reference to the addon's `exports` object. The callback associated with the weak
@@ -259,6 +261,7 @@ signature.
In order to be loaded from multiple Node.js environments,
such as a main thread and a Worker thread, an add-on needs to either:
+
- Be an N-API addon, or
- Be declared as context-aware using `NODE_MODULE_INIT()` as described above
diff --git a/doc/api/assert.md b/doc/api/assert.md
index 6057ba5c2a..db222580c3 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -19,6 +19,7 @@ will be instances of the `AssertionError` class.
<!-- YAML
added: v0.1.21
-->
+
* `options` {Object}
* `message` {string} If provided, the error message is set to this value.
* `actual` {any} The `actual` property on the error instance.
@@ -145,6 +146,7 @@ assert.deepEqual(/a/gi, new Date());
<!-- YAML
added: v0.5.9
-->
+
* `value` {any} The input that is checked for being truthy.
* `message` {string|Error}
@@ -174,6 +176,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5910
description: Handle non-`Uint8Array` typed arrays correctly.
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -291,6 +294,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5910
description: Handle non-`Uint8Array` typed arrays correctly.
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -420,6 +424,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
<!-- YAML
added: v10.0.0
-->
+
* `asyncFn` {Function|Promise}
* `error` {RegExp|Function}
* `message` {string}
@@ -476,6 +481,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/3276
description: The `error` parameter can now be an arrow function.
-->
+
* `fn` {Function}
* `error` {RegExp|Function}
* `message` {string}
@@ -544,6 +550,7 @@ assert.doesNotThrow(
<!-- YAML
added: v0.1.21
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -583,6 +590,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
<!-- YAML
added: v0.1.21
-->
+
* `message` {string|Error} **Default:** `'Failed'`
Throws an `AssertionError` with the provided error message or a default error
@@ -614,6 +622,7 @@ changes:
description: Calling `assert.fail()` with more than one argument is
deprecated and emits a warning.
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -680,6 +689,7 @@ changes:
description: Value may now only be `undefined` or `null`. Before all falsy
values were handled the same as `null` and did not throw.
-->
+
* `value` {any}
Throws `value` if `value` is not `undefined` or `null`. This is useful when
@@ -733,6 +743,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5910
description: Handle non-`Uint8Array` typed arrays correctly.
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -814,6 +825,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5910
description: Handle non-`Uint8Array` typed arrays correctly.
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -837,6 +849,7 @@ instead of the `AssertionError`.
<!-- YAML
added: v0.1.21
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -879,6 +892,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/17003
description: Used comparison changed from Strict Equality to `Object.is()`
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -916,6 +930,7 @@ changes:
description: The `assert.ok()` (no arguments) will now use a predefined
error message.
-->
+
* `value` {any}
* `message` {string|Error}
@@ -978,6 +993,7 @@ assert(0);
<!-- YAML
added: v10.0.0
-->
+
* `asyncFn` {Function|Promise}
* `error` {RegExp|Function|Object|Error}
* `message` {string}
@@ -1040,6 +1056,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/17003
description: Used comparison changed from Strict Equality to `Object.is()`
-->
+
* `actual` {any}
* `expected` {any}
* `message` {string|Error}
@@ -1096,6 +1113,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/3276
description: The `error` parameter can now be an arrow function.
-->
+
* `fn` {Function}
* `error` {RegExp|Function|Object|Error}
* `message` {string}
diff --git a/doc/api/console.md b/doc/api/console.md
index c03e7b8233..b9a5ea3035 100644
--- a/doc/api/console.md
+++ b/doc/api/console.md
@@ -138,6 +138,7 @@ changes:
description: The implementation is now spec compliant and does not throw
anymore.
-->
+
* `value` {any} The value tested for being truthy.
* `...message` {any} All arguments besides `value` are used as error message.
@@ -233,6 +234,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/17033
description: "`console.debug` is now an alias for `console.log`."
-->
+
* `data` {any}
* `...args` {any}
@@ -242,6 +244,7 @@ The `console.debug()` function is an alias for [`console.log()`][].
<!-- YAML
added: v0.1.101
-->
+
* `obj` {any}
* `options` {Object}
* `showHidden` {boolean} If `true` then the object's non-enumerable and symbol
@@ -264,6 +267,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/17152
description: "`console.dirxml` now calls `console.log` for its arguments."
-->
+
* `...data` {any}
This method calls `console.log()` passing it the arguments received.
@@ -273,6 +277,7 @@ This method does not produce any XML formatting.
<!-- YAML
added: v0.1.100
-->
+
* `data` {any}
* `...args` {any}
@@ -323,6 +328,7 @@ Decreases indentation of subsequent lines by two spaces.
<!-- YAML
added: v0.1.100
-->
+
* `data` {any}
* `...args` {any}
@@ -332,6 +338,7 @@ The `console.info()` function is an alias for [`console.log()`][].
<!-- YAML
added: v0.1.100
-->
+
* `data` {any}
* `...args` {any}
@@ -391,6 +398,7 @@ console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }], ['a']);
<!-- YAML
added: v0.1.104
-->
+
* `label` {string} **Default:** `'default'`
Starts a timer that can be used to compute the duration of an operation. Timers
@@ -407,6 +415,7 @@ changes:
description: This method no longer supports multiple calls that don’t map
to individual `console.time()` calls; see below for details.
-->
+
* `label` {string} **Default:** `'default'`
Stops a timer that was previously started by calling [`console.time()`][] and
@@ -423,6 +432,7 @@ console.timeEnd('100-elements');
<!-- YAML
added: v10.7.0
-->
+
* `label` {string} **Default:** `'default'`
* `...data` {any}
@@ -442,6 +452,7 @@ console.timeEnd('process');
<!-- YAML
added: v0.1.104
-->
+
* `message` {any}
* `...args` {any}
@@ -468,6 +479,7 @@ console.trace('Show me');
<!-- YAML
added: v0.1.100
-->
+
* `data` {any}
* `...args` {any}
@@ -482,6 +494,7 @@ not display anything unless used in conjunction with the [inspector][]
<!-- YAML
added: v8.0.0
-->
+
* `label` {string} **Default:** `'default'`
This method does not display anything unless used in the inspector. The
@@ -492,6 +505,7 @@ This method does not display anything unless used in the inspector. The
<!-- YAML
added: v8.0.0
-->
+
* `label` {string}
This method does not display anything unless used in the inspector. The
@@ -510,6 +524,7 @@ console.profileEnd('MyLabel');
<!-- YAML
added: v8.0.0
-->
+
* `label` {string}
This method does not display anything unless used in the inspector. Stops the
@@ -524,6 +539,7 @@ stopped.
<!-- YAML
added: v8.0.0
-->
+
* `label` {string}
This method does not display anything unless used in the inspector. The
@@ -534,6 +550,7 @@ This method does not display anything unless used in the inspector. The
<!-- YAML
added: v8.0.0
-->
+
* `label` {string} **Default:** `'default'`
This method does not display anything unless used in the inspector. The
@@ -543,6 +560,7 @@ This method does not display anything unless used in the inspector. The
<!-- YAML
added: v8.0.0
-->
+
* `label` {string} **Default:** `'default'`
This method does not display anything unless used in the inspector. The
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index dbef108f89..137d6e0508 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -55,6 +55,7 @@ data. The most common usage is handling output generated by the HTML5
<!-- YAML
added: v9.0.0
-->
+
* `spkac` {string | Buffer | TypedArray | DataView}
* Returns: {Buffer} The challenge component of the `spkac` data structure, which
includes a public key and a challenge.
@@ -71,6 +72,7 @@ console.log(challenge.toString('utf8'));
<!-- YAML
added: v9.0.0
-->
+
* `spkac` {string | Buffer | TypedArray | DataView}
* `encoding` {string} The [encoding][] of the `spkac` string.
* Returns: {Buffer} The public key component of the `spkac` data structure,
@@ -88,6 +90,7 @@ console.log(publicKey);
<!-- YAML
added: v9.0.0
-->
+
* `spkac` {Buffer | TypedArray | DataView}
* Returns: {boolean} `true` if the given `spkac` data structure is valid,
`false` otherwise.
@@ -121,6 +124,7 @@ const cert2 = crypto.Certificate();
<!-- YAML
added: v0.11.8
-->
+
* `spkac` {string | Buffer | TypedArray | DataView}
* Returns: {Buffer} The challenge component of the `spkac` data structure, which
includes a public key and a challenge.
@@ -137,6 +141,7 @@ console.log(challenge.toString('utf8'));
<!-- YAML
added: v0.11.8
-->
+
* `spkac` {string | Buffer | TypedArray | DataView}
* Returns: {Buffer} The public key component of the `spkac` data structure,
which includes a public key and a challenge.
@@ -153,6 +158,7 @@ console.log(publicKey);
<!-- YAML
added: v0.11.8
-->
+
* `spkac` {Buffer | TypedArray | DataView}
* Returns: {boolean} `true` if the given `spkac` data structure is valid,
`false` otherwise.
@@ -263,6 +269,7 @@ console.log(encrypted);
<!-- YAML
added: v0.1.94
-->
+
* `outputEncoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string} Any remaining enciphered contents.
If `outputEncoding` is specified, a string is
@@ -276,6 +283,7 @@ once will result in an error being thrown.
<!-- YAML
added: v1.0.0
-->
+
* `buffer` {Buffer}
* `options` {Object} [`stream.transform` options][]
- `plaintextLength` {number}
@@ -295,6 +303,7 @@ The `cipher.setAAD()` method must be called before [`cipher.update()`][].
<!-- YAML
added: v1.0.0
-->
+
* Returns: {Buffer} When using an authenticated encryption mode (`GCM`, `CCM`
and `OCB` are currently supported), the `cipher.getAuthTag()` method returns a
[`Buffer`][] containing the _authentication tag_ that has been computed from
@@ -307,6 +316,7 @@ been completed using the [`cipher.final()`][] method.
<!-- YAML
added: v0.7.1
-->
+
* `autoPadding` {boolean} **Default:** `true`
* Returns: {Cipher} for method chaining.
@@ -330,6 +340,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5522
description: The default `inputEncoding` changed from `binary` to `utf8`.
-->
+
* `data` {string | Buffer | TypedArray | DataView}
* `inputEncoding` {string} The [encoding][] of the data.
* `outputEncoding` {string} The [encoding][] of the return value.
@@ -452,6 +463,7 @@ console.log(decrypted);
<!-- YAML
added: v0.1.94
-->
+
* `outputEncoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string} Any remaining deciphered contents.
If `outputEncoding` is specified, a string is
@@ -469,6 +481,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/9398
description: This method now returns a reference to `decipher`.
-->
+
* `buffer` {Buffer | TypedArray | DataView}
* `options` {Object} [`stream.transform` options][]
- `plaintextLength` {number}
@@ -495,6 +508,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/9398
description: This method now returns a reference to `decipher`.
-->
+
* `buffer` {Buffer | TypedArray | DataView}
* Returns: {Decipher} for method chaining.
@@ -513,6 +527,7 @@ The `decipher.setAuthTag()` method must be called before
<!-- YAML
added: v0.7.1
-->
+
* `autoPadding` {boolean} **Default:** `true`
* Returns: {Decipher} for method chaining.
@@ -534,6 +549,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5522
description: The default `inputEncoding` changed from `binary` to `utf8`.
-->
+
* `data` {string | Buffer | TypedArray | DataView}
* `inputEncoding` {string} The [encoding][] of the `data` string.
* `outputEncoding` {string} The [encoding][] of the return value.
@@ -589,6 +605,7 @@ assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
<!-- YAML
added: v0.5.0
-->
+
* `otherPublicKey` {string | Buffer | TypedArray | DataView}
* `inputEncoding` {string} The [encoding][] of an `otherPublicKey` string.
* `outputEncoding` {string} The [encoding][] of the return value.
@@ -609,6 +626,7 @@ If `outputEncoding` is given a string is returned; otherwise, a
<!-- YAML
added: v0.5.0
-->
+
* `encoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string}
@@ -622,6 +640,7 @@ If `encoding` is provided a string is returned; otherwise a
<!-- YAML
added: v0.5.0
-->
+
* `encoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string}
@@ -633,6 +652,7 @@ returned; otherwise a [`Buffer`][] is returned.
<!-- YAML
added: v0.5.0
-->
+
* `encoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string}
@@ -644,6 +664,7 @@ returned; otherwise a [`Buffer`][] is returned.
<!-- YAML
added: v0.5.0
-->
+
* `encoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string}
@@ -655,6 +676,7 @@ string is returned; otherwise a [`Buffer`][] is returned.
<!-- YAML
added: v0.5.0
-->
+
* `encoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string}
@@ -666,6 +688,7 @@ string is returned; otherwise a [`Buffer`][] is returned.
<!-- YAML
added: v0.5.0
-->
+
* `privateKey` {string | Buffer | TypedArray | DataView}
* `encoding` {string} The [encoding][] of the `privateKey` string.
@@ -678,6 +701,7 @@ to be a [`Buffer`][], `TypedArray`, or `DataView`.
<!-- YAML
added: v0.5.0
-->
+
* `publicKey` {string | Buffer | TypedArray | DataView}
* `encoding` {string} The [encoding][] of the `publicKey` string.
@@ -820,6 +844,7 @@ changes:
description: Changed error format to better support invalid public key
error
-->
+
* `otherPublicKey` {string | Buffer | TypedArray | DataView}
* `inputEncoding` {string} The [encoding][] of the `otherPublicKey` string.
* `outputEncoding` {string} The [encoding][] of the return value.
@@ -846,6 +871,7 @@ its recommended for developers to handle this exception accordingly.
<!-- YAML
added: v0.11.14
-->
+
* `encoding` {string} The [encoding][] of the return value.
* `format` {string} **Default:** `'uncompressed'`
* Returns: {Buffer | string}
@@ -865,6 +891,7 @@ is returned.
<!-- YAML
added: v0.11.14
-->
+
* `encoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string} The EC Diffie-Hellman in the specified `encoding`.
@@ -875,6 +902,7 @@ returned.
<!-- YAML
added: v0.11.14
-->
+
* `encoding` {string} The [encoding][] of the return value.
* `format` {string} **Default:** `'uncompressed'`
* Returns: {Buffer | string} The EC Diffie-Hellman public key in the specified
@@ -891,6 +919,7 @@ returned.
<!-- YAML
added: v0.11.14
-->
+
* `privateKey` {string | Buffer | TypedArray | DataView}
* `encoding` {string} The [encoding][] of the `privateKey` string.
@@ -1016,6 +1045,7 @@ console.log(hash.digest('hex'));
<!-- YAML
added: v0.1.92
-->
+
* `encoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string}
@@ -1035,6 +1065,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5522
description: The default `inputEncoding` changed from `binary` to `utf8`.
-->
+
* `data` {string | Buffer | TypedArray | DataView}
* `inputEncoding` {string} The [encoding][] of the `data` string.
@@ -1112,6 +1143,7 @@ console.log(hmac.digest('hex'));
<!-- YAML
added: v0.1.94
-->
+
* `encoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string}
@@ -1130,6 +1162,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5522
description: The default `inputEncoding` changed from `binary` to `utf8`.
-->
+
* `data` {string | Buffer | TypedArray | DataView}
* `inputEncoding` {string} The [encoding][] of the `data` string.
@@ -1178,6 +1211,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/26319
description: Added support for `'ed25519'` and `'ed448'`.
-->
+
* {string}
For asymmetric keys, this property represents the type of the key. Supported key
@@ -1199,6 +1233,7 @@ keys.
<!-- YAML
added: v11.6.0
-->
+
* `options`: {Object}
* Returns: {string | Buffer}
@@ -1241,6 +1276,7 @@ PKCS#1 and SEC1 encryption.
<!-- YAML
added: v11.6.0
-->
+
* {number}
For secret keys, this property represents the size of the key in bytes. This
@@ -1250,6 +1286,7 @@ property is `undefined` for asymmetric keys.
<!-- YAML
added: v11.6.0
-->
+
* {string}
Depending on the type of this `KeyObject`, this property is either
@@ -1331,6 +1368,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/11705
description: Support for RSASSA-PSS and additional options was added.
-->
+
* `privateKey` {Object | string | Buffer | KeyObject}
- `padding` {integer}
- `saltLength` {integer}
@@ -1372,6 +1410,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5522
description: The default `inputEncoding` changed from `binary` to `utf8`.
-->
+
* `data` {string | Buffer | TypedArray | DataView}
* `inputEncoding` {string} The [encoding][] of the `data` string.
@@ -1411,6 +1450,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/5522
description: The default `inputEncoding` changed from `binary` to `utf8`.
-->
+
* `data` {string | Buffer | TypedArray | DataView}
* `inputEncoding` {string} The [encoding][] of the `data` string.
@@ -1436,6 +1476,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/11705
description: Support for RSASSA-PSS and additional options was added.
-->
+
* `object` {Object | string | Buffer | KeyObject}
- `padding` {integer}
- `saltLength` {integer}
@@ -1483,6 +1524,7 @@ be passed instead of a public key.
<!-- YAML
added: v6.3.0
-->
+
* Returns: {Object} An object containing commonly used constants for crypto and
security related operations. The specific constants currently defined are
described in [Crypto Constants][].
@@ -1598,6 +1640,7 @@ changes:
description: The `iv` parameter may now be `null` for ciphers which do not
need an initialization vector.
-->
+
* `algorithm` {string}
* `key` {string | Buffer | TypedArray | DataView | KeyObject}
* `iv` {string | Buffer | TypedArray | DataView}
@@ -1691,6 +1734,7 @@ changes:
description: The `iv` parameter may now be `null` for ciphers which do not
need an initialization vector.
-->
+
* `algorithm` {string}
* `key` {string | Buffer | TypedArray | DataView}
* `iv` {string | Buffer | TypedArray | DataView}
@@ -1740,6 +1784,7 @@ changes:
description: The default for the encoding parameters changed
from `binary` to `utf8`.
-->
+
* `prime` {string | Buffer | TypedArray | DataView}
* `primeEncoding` {string} The [encoding][] of the `prime` string.
* `generator` {number | string | Buffer | TypedArray | DataView} **Default:**
@@ -1763,6 +1808,7 @@ otherwise a number, [`Buffer`][], `TypedArray`, or `DataView` is expected.
<!-- YAML
added: v0.5.0
-->
+
* `primeLength` {number}
* `generator` {number | string | Buffer | TypedArray | DataView} **Default:**
`2`
@@ -1786,6 +1832,7 @@ An alias for [`crypto.getDiffieHellman()`][]
<!-- YAML
added: v0.11.14
-->
+
* `curveName` {string}
* Returns: {ECDH}
@@ -1803,6 +1850,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/28805
description: The `outputLength` option was added for XOF hash functions.
-->
+
* `algorithm` {string}
* `options` {Object} [`stream.transform` options][]
* Returns: {Hash}
@@ -1848,6 +1896,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/24234
description: The `key` argument can now be a `KeyObject`.
-->
+
* `algorithm` {string}
* `key` {string | Buffer | TypedArray | DataView | KeyObject}
* `options` {Object} [`stream.transform` options][]
@@ -1891,6 +1940,7 @@ input.on('readable', () => {
<!-- YAML
added: v11.6.0
-->
+
* `key` {Object | string | Buffer}
- `key`: {string | Buffer} The key material, either in PEM or DER format.
- `format`: {string} Must be `'pem'` or `'der'`. **Default:** `'pem'`.
@@ -1918,6 +1968,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/25217
description: The `key` argument can now be a private key.
-->
+
* `key` {Object | string | Buffer | KeyObject}
- `key`: {string | Buffer}
- `format`: {string} Must be `'pem'` or `'der'`. **Default:** `'pem'`.
@@ -1944,6 +1995,7 @@ and it will be impossible to extract the private key from the returned object.
<!-- YAML
added: v11.6.0
-->
+
* `key` {Buffer}
* Returns: {KeyObject}
@@ -1954,6 +2006,7 @@ encryption or `Hmac`.
<!-- YAML
added: v0.1.92
-->
+
* `algorithm` {string}
* `options` {Object} [`stream.Writable` options][]
* Returns: {Sign}
@@ -1972,6 +2025,7 @@ algorithm names.
<!-- YAML
added: v0.1.92
-->
+
* `algorithm` {string}
* `options` {Object} [`stream.Writable` options][]
* Returns: {Verify}
@@ -2002,6 +2056,7 @@ changes:
description: The `generateKeyPair` and `generateKeyPairSync` functions now
produce key objects if no encoding was specified.
-->
+
* `type`: {string} Must be `'rsa'`, `'dsa'`, `'ec'`, `'ed25519'`, `'ed448'`,
`'x25519'`, or `'x448'`.
* `options`: {Object}
@@ -2063,6 +2118,7 @@ changes:
description: The `generateKeyPair` and `generateKeyPairSync` functions now
produce key objects if no encoding was specified.
-->
+
* `type`: {string} Must be `'rsa'`, `'dsa'`, `'ec'`, `'ed25519'`, or `'ed448'`.
* `options`: {Object}
- `modulusLength`: {number} Key size in bits (RSA, DSA).
@@ -2111,6 +2167,7 @@ it will be a buffer containing the data encoded as DER.
<!-- YAML
added: v0.9.3
-->
+
* Returns: {string[]} An array with the names of the supported cipher
algorithms.
@@ -2123,6 +2180,7 @@ console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
<!-- YAML
added: v2.3.0
-->
+
* Returns: {string[]} An array with the names of the supported elliptic curves.
```js
@@ -2134,6 +2192,7 @@ console.log(curves); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]
<!-- YAML
added: v0.7.5
-->
+
* `groupName` {string}
* Returns: {DiffieHellman}
@@ -2169,6 +2228,7 @@ console.log(aliceSecret === bobSecret);
<!-- YAML
added: v10.0.0
-->
+
* Returns: {boolean} `true` if and only if a FIPS compliant crypto provider is
currently in use.
@@ -2176,6 +2236,7 @@ added: v10.0.0
<!-- YAML
added: v0.9.3
-->
+
* Returns: {string[]} An array of the names of the supported hash algorithms,
such as `'RSA-SHA256'`. Hash algorithms are also called "digest" algorithms.
@@ -2200,6 +2261,7 @@ changes:
description: The default encoding for `password` if it is a string changed
from `binary` to `utf8`.
-->
+
* `password` {string|Buffer|TypedArray|DataView}
* `salt` {string|Buffer|TypedArray|DataView}
* `iterations` {number}
@@ -2271,6 +2333,7 @@ changes:
description: The default encoding for `password` if it is a string changed
from `binary` to `utf8`.
-->
+
* `password` {string|Buffer|TypedArray|DataView}
* `salt` {string|Buffer|TypedArray|DataView}
* `iterations` {number}
@@ -2327,6 +2390,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/24234
description: This function now supports key objects.
-->
+
* `privateKey` {Object | string | Buffer | KeyObject}
- `oaepHash` {string} The hash function to use for OAEP padding.
**Default:** `'sha1'`
@@ -2353,6 +2417,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/24234
description: This function now supports key objects.
-->
+
* `privateKey` {Object | string | Buffer | KeyObject}
- `key` {string | Buffer | KeyObject} A PEM encoded private key.
- `passphrase` {string | Buffer} An optional passphrase for the private key.
@@ -2378,6 +2443,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/24234
description: This function now supports key objects.
-->
+
* `key` {Object | string | Buffer | KeyObject}
- `passphrase` {string | Buffer} An optional passphrase for the private key.
- `padding` {crypto.constants} An optional padding value defined in
@@ -2408,6 +2474,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/24234
description: This function now supports key objects.
-->
+
* `key` {Object | string | Buffer | KeyObject}
- `key` {string | Buffer | KeyObject} A PEM encoded public or private key.
- `oaepHash` {string} The hash function to use for OAEP padding.
@@ -2441,6 +2508,7 @@ changes:
description: Passing `null` as the `callback` argument now throws
`ERR_INVALID_CALLBACK`.
-->
+
* `size` {number}
* `callback` {Function}
- `err` {Error}
@@ -2623,6 +2691,7 @@ changes:
description: The `cost`, `blockSize` and `parallelization` option names
have been added.
-->
+
* `password` {string|Buffer|TypedArray|DataView}
* `salt` {string|Buffer|TypedArray|DataView}
* `keylen` {number}
@@ -2680,6 +2749,7 @@ changes:
description: The `cost`, `blockSize` and `parallelization` option names
have been added.
-->
+
* `password` {string|Buffer|TypedArray|DataView}
* `salt` {string|Buffer|TypedArray|DataView}
* `keylen` {number}
@@ -2722,6 +2792,7 @@ console.log(key2.toString('hex')); // '3745e48...aa39b34'
<!-- YAML
added: v0.11.11
-->
+
* `engine` {string}
* `flags` {crypto.constants} **Default:** `crypto.constants.ENGINE_METHOD_ALL`
@@ -2755,6 +2826,7 @@ The flags below are deprecated in OpenSSL-1.1.0.
<!-- YAML
added: v10.0.0
-->
+
* `bool` {boolean} `true` to enable FIPS mode.
Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build.
@@ -2764,6 +2836,7 @@ Throws an error if FIPS mode is not available.
<!-- YAML
added: v12.0.0
-->
+
* `algorithm` {string | null | undefined}
* `data` {Buffer | TypedArray | DataView}
* `key` {Object | string | Buffer | KeyObject}
@@ -2793,6 +2866,7 @@ additional properties can be passed:
<!-- YAML
added: v6.6.0
-->
+
* `a` {Buffer | TypedArray | DataView}
* `b` {Buffer | TypedArray | DataView}
* Returns: {boolean}
@@ -2814,6 +2888,7 @@ not introduce timing vulnerabilities.
<!-- YAML
added: v12.0.0
-->
+
* `algorithm` {string | null | undefined}
* `data` {Buffer | TypedArray | DataView}
* `key` {Object | string | Buffer | KeyObject}
diff --git a/doc/api/dgram.md b/doc/api/dgram.md
index f4ae367527..38d9492be8 100644
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@@ -83,6 +83,7 @@ added: v0.1.99
The `'message'` event is emitted when a new datagram is available on a socket.
The event handler function is passed two arguments: `msg` and `rinfo`.
+
* `msg` {Buffer} The message.
* `rinfo` {Object} Remote address information.
* `address` {string} The sender address.
@@ -241,6 +242,7 @@ socket.bind({
<!-- YAML
added: v0.1.99
-->
+
* `callback` {Function} Called when the socket has been closed.
Close the underlying socket and stop listening for data on it. If a callback is
diff --git a/doc/api/dns.md b/doc/api/dns.md
index 43f78af7c7..f8b051b884 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -139,6 +139,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/744
description: The `all` option is supported now.
-->
+
* `hostname` {string}
* `options` {integer | Object}
- `family` {integer} The record family. Must be `4`, `6`, or `0`. The value
@@ -221,6 +222,7 @@ on some operating systems (e.g FreeBSD 10.1).
<!-- YAML
added: v0.11.14
-->
+
* `address` {string}
* `port` {number}
* `callback` {Function}
@@ -252,6 +254,7 @@ If this method is invoked as its [`util.promisify()`][]ed version, it returns a
<!-- YAML
added: v0.1.27
-->
+
* `hostname` {string} Hostname to resolve.
* `rrtype` {string} Resource record type. **Default:** `'A'`.
* `callback` {Function}
@@ -289,6 +292,7 @@ changes:
description: This method now supports passing `options`,
specifically `options.ttl`.
-->
+
* `hostname` {string} Hostname to resolve.
* `options` {Object}
- `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record.
@@ -313,6 +317,7 @@ changes:
description: This method now supports passing `options`,
specifically `options.ttl`.
-->
+
* `hostname` {string} Hostname to resolve.
* `options` {Object}
- `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record.
@@ -380,6 +385,7 @@ queries. It may be better to call individual methods like [`dns.resolve4()`][],
<!-- YAML
added: v0.3.2
-->
+
* `hostname` {string}
* `callback` {Function}
- `err` {Error}
@@ -394,6 +400,7 @@ will contain an array of canonical name records available for the `hostname`
<!-- YAML
added: v0.1.27
-->
+
* `hostname` {string}
* `callback` {Function}
- `err` {Error}
@@ -408,6 +415,7 @@ property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`).
<!-- YAML
added: v0.9.12
-->
+
* `hostname` {string}
* `callback` {Function}
- `err` {Error}
@@ -440,6 +448,7 @@ function will contain an array of objects with the following properties:
<!-- YAML
added: v0.1.90
-->
+
* `hostname` {string}
* `callback` {Function}
- `err` {Error}
@@ -454,6 +463,7 @@ contain an array of name server records available for `hostname`
<!-- YAML
added: v6.0.0
-->
+
* `hostname` {string}
* `callback` {Function}
- `err` {Error}
@@ -467,6 +477,7 @@ be an array of strings containing the reply records.
<!-- YAML
added: v0.11.10
-->
+
* `hostname` {string}
* `callback` {Function}
- `err` {Error}
@@ -501,6 +512,7 @@ be an object with the following properties:
<!-- YAML
added: v0.1.27
-->
+
* `hostname` {string}
* `callback` {Function}
- `err` {Error}
@@ -529,6 +541,7 @@ be an array of objects with the following properties:
<!-- YAML
added: v0.1.27
-->
+
* `hostname` {string}
* `callback` {Function}
- `err` {Error}
@@ -545,6 +558,7 @@ treated separately.
<!-- YAML
added: v0.1.16
-->
+
* `ip` {string}
* `callback` {Function}
- `err` {Error}
@@ -560,6 +574,7 @@ one of the [DNS error codes][].
<!-- YAML
added: v0.11.3
-->
+
* `servers` {string[]} array of [RFC 5952][] formatted addresses
Sets the IP address and port of servers to be used when performing DNS
@@ -668,6 +683,7 @@ section if a custom port is used.
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
* `options` {integer | Object}
- `family` {integer} The record family. Must be `4`, `6`, or `0`. The value
@@ -732,6 +748,7 @@ dnsPromises.lookup('example.com', options).then((result) => {
<!-- YAML
added: v10.6.0
-->
+
* `address` {string}
* `port` {number}
@@ -757,6 +774,7 @@ dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string} Hostname to resolve.
* `rrtype` {string} Resource record type. **Default:** `'A'`.
@@ -786,6 +804,7 @@ is one of the [DNS error codes](#dns_error_codes).
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string} Hostname to resolve.
* `options` {Object}
- `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record.
@@ -801,6 +820,7 @@ addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string} Hostname to resolve.
* `options` {Object}
- `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record.
@@ -816,6 +836,7 @@ addresses.
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query).
@@ -860,6 +881,7 @@ Here is an example of the result object:
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve `CNAME` records for the `hostname`. On success,
@@ -870,6 +892,7 @@ the `hostname` (e.g. `['bar.example.com']`).
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve mail exchange records (`MX` records) for the
@@ -881,6 +904,7 @@ containing both a `priority` and `exchange` property (e.g.
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve regular expression based records (`NAPTR`
@@ -910,6 +934,7 @@ of objects with the following properties:
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve name server records (`NS` records) for the
@@ -921,6 +946,7 @@ records available for `hostname` (e.g.
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve pointer records (`PTR` records) for the
@@ -931,6 +957,7 @@ containing the reply records.
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve a start of authority record (`SOA` record) for
@@ -962,6 +989,7 @@ following properties:
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve service records (`SRV` records) for the
@@ -987,6 +1015,7 @@ the following properties:
<!-- YAML
added: v10.6.0
-->
+
* `hostname` {string}
Uses the DNS protocol to resolve text queries (`TXT` records) for the
@@ -1000,6 +1029,7 @@ treated separately.
<!-- YAML
added: v10.6.0
-->
+
* `ip` {string}
Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an
@@ -1012,6 +1042,7 @@ is one of the [DNS error codes](#dns_error_codes).
<!-- YAML
added: v10.6.0
-->
+
* `servers` {string[]} array of [RFC 5952][] formatted addresses
Sets the IP address and port of servers to be used when performing DNS
diff --git a/doc/api/esm.md b/doc/api/esm.md
index 1d6ae5d599..114e3319e1 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -710,6 +710,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
<summary>Resolver algorithm specification</summary>
**ESM_RESOLVE**(_specifier_, _parentURL_, _isMain_)
+
> 1. Let _resolvedURL_ be **undefined**.
> 1. If _specifier_ is a valid URL, then
> 1. Set _resolvedURL_ to the result of parsing and reserializing
@@ -733,6 +734,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
> 1. Load _resolvedURL_ as module format, _format_.
**PACKAGE_RESOLVE**(_packageSpecifier_, _parentURL_)
+
> 1. Let _packageName_ be *undefined*.
> 1. Let _packageSubpath_ be *undefined*.
> 1. If _packageSpecifier_ is an empty string, then
@@ -779,6 +781,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
> 1. Throw a _Module Not Found_ error.
**PACKAGE_MAIN_RESOLVE**(_packageURL_, _pjson_)
+
> 1. If _pjson_ is **null**, then
> 1. Throw a _Module Not Found_ error.
> 1. If _pjson.main_ is a String, then
@@ -794,6 +797,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
> 1. Return _legacyMainURL_.
**PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _packagePath_, _exports_)
+
> 1. If _exports_ is an Object, then
> 1. Set _packagePath_ to _"./"_ concatenated with _packagePath_.
> 1. If _packagePath_ is a key of _exports_, then
@@ -812,6 +816,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
> 1. Throw a _Module Not Found_ error.
**PACKAGE_EXPORTS_TARGET_RESOLVE**(_packageURL_, _target_, _subpath_)
+
> 1. If _target_ is a String, then
> 1. If _target_ does not start with _"./"_, throw a _Module Not Found_
> error.
@@ -837,6 +842,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
> 1. Throw a _Module Not Found_ error.
**ESM_FORMAT**(_url_, _isMain_)
+
> 1. Assert: _url_ corresponds to an existing file.
> 1. Let _pjson_ be the result of **READ_PACKAGE_SCOPE**(_url_).
> 1. If _url_ ends in _".mjs"_, then
@@ -854,6 +860,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
> 1. Throw an _Unsupported File Extension_ error.
**READ_PACKAGE_SCOPE**(_url_)
+
> 1. Let _scopeURL_ be _url_.
> 1. While _scopeURL_ is not the file system root,
> 1. If _scopeURL_ ends in a _"node_modules"_ path segment, return **null**.
@@ -864,6 +871,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
> 1. Return **null**.
**READ_PACKAGE_JSON**(_packageURL_)
+
> 1. Let _pjsonURL_ be the resolution of _"package.json"_ within _packageURL_.
> 1. If the file at _pjsonURL_ does not exist, then
> 1. Return **null**.
diff --git a/doc/api/events.md b/doc/api/events.md
index 021c6b0598..3b92a04ca5 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -228,6 +228,7 @@ The `'removeListener'` event is emitted *after* the `listener` is removed.
added: v0.9.12
deprecated: v4.0.0
-->
+
* `emitter` {EventEmitter} The emitter to query
* `eventName` {string|symbol} The event name
@@ -288,6 +289,7 @@ Its `name` property is set to `'MaxListenersExceededWarning'`.
<!-- YAML
added: v0.1.26
-->
+
* `eventName` {string|symbol}
* `listener` {Function}
@@ -297,8 +299,9 @@ Alias for `emitter.on(eventName, listener)`.
<!-- YAML
added: v0.1.26
-->
+
* `eventName` {string|symbol}
-- `...args` {any}
+* `...args` {any}
* Returns: {boolean}
Synchronously calls each of the listeners registered for the event named
@@ -393,6 +396,7 @@ changes:
description: For listeners attached using `.once()` this returns the
original listeners instead of wrapper functions now.
-->
+
* `eventName` {string|symbol}
* Returns: {Function[]}
@@ -536,6 +540,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
<!-- YAML
added: v0.1.26
-->
+
* `eventName` {string|symbol}
* Returns: {EventEmitter}
@@ -551,6 +556,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
<!-- YAML
added: v0.1.26
-->
+
* `eventName` {string|symbol}
* `listener` {Function}
* Returns: {EventEmitter}
@@ -640,6 +646,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
<!-- YAML
added: v0.3.5
-->
+
* `n` {integer}
* Returns: {EventEmitter}
@@ -656,6 +663,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
<!-- YAML
added: v9.4.0
-->
+
* `eventName` {string|symbol}
* Returns: {Function[]}
@@ -690,6 +698,7 @@ emitter.emit('log');
<!-- YAML
added: v11.13.0
-->
+
* `emitter` {EventEmitter}
* `name` {string}
* Returns: {Promise}
diff --git a/doc/api/fs.md b/doc/api/fs.md
index b1414b6e54..8077c533f8 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -2696,6 +2696,7 @@ The `fs.readFile()` function buffers the entire file. To minimize memory costs,
when possible prefer streaming via `fs.createReadStream()`.
### File Descriptors
+
1. Any specified file descriptor has to support reading.
2. If a file descriptor is specified as the `path`, it will not be closed
automatically.
@@ -3436,6 +3437,7 @@ changes:
Change the file system timestamps of the object referenced by `path`.
The `atime` and `mtime` arguments follow these rules:
+
- Values can be either numbers representing Unix epoch time, `Date`s, or a
numeric string like `'123456789.0'`.
- If the value can not be converted to a number, or is `NaN`, `Infinity` or
@@ -3637,6 +3639,7 @@ reappearance) will be the same as the `previousStat` of the first callback
event (its disappearance).
This happens when:
+
- the file is deleted, followed by a restore
- the file is renamed twice - the second time back to its original name
@@ -3991,6 +3994,7 @@ rejected.
<!-- YAML
added: v10.0.0
-->
+
* `data` {string|Buffer}
* `options` {Object|string}
* `encoding` {string|null} **Default:** `'utf8'`
@@ -4010,6 +4014,7 @@ The `FileHandle` must have been opened for appending.
<!-- YAML
added: v10.0.0
-->
+
* `mode` {integer}
* Returns: {Promise}
@@ -4020,6 +4025,7 @@ arguments upon success.
<!-- YAML
added: v10.0.0
-->
+
* `uid` {integer}
* `gid` {integer}
* Returns: {Promise}
@@ -4055,6 +4061,7 @@ async function openAndClose() {
<!-- YAML
added: v10.0.0
-->
+
* Returns: {Promise}
Asynchronous fdatasync(2). The `Promise` is resolved with no arguments upon
@@ -4071,6 +4078,7 @@ added: v10.0.0
<!-- YAML
added: v10.0.0
-->
+
* `buffer` {Buffer|Uint8Array}
* `offset` {integer}
* `length` {integer}
@@ -4098,6 +4106,7 @@ property that is a reference to the passed in `buffer` argument.
<!-- YAML
added: v10.0.0
-->
+
* `options` {Object|string}
* `encoding` {string|null} **Default:** `null`
* `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
@@ -4132,6 +4141,7 @@ changes:
description: Accepts an additional `options` object to specify whether
the numeric values returned should be bigint.
-->
+
* `options` {Object}
* `bigint` {boolean} Whether the numeric values in the returned
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
@@ -4143,6 +4153,7 @@ Retrieves the [`fs.Stats`][] for the file.
<!-- YAML
added: v10.0.0
-->
+
* Returns: {Promise}
Asynchronous fsync(2). The `Promise` is resolved with no arguments upon
@@ -4152,6 +4163,7 @@ success.
<!-- YAML
added: v10.0.0
-->
+
* `len` {integer} **Default:** `0`
* Returns: {Promise}
@@ -4220,6 +4232,7 @@ The last three bytes are null bytes (`'\0'`), to compensate the over-truncation.
<!-- YAML
added: v10.0.0
-->
+
* `atime` {number|string|Date}
* `mtime` {number|string|Date}
* Returns: {Promise}
@@ -4234,6 +4247,7 @@ This function does not work on AIX versions before 7.1, it will resolve the
<!-- YAML
added: v10.0.0
-->
+
* `buffer` {Buffer|Uint8Array}
* `offset` {integer}
* `length` {integer}
@@ -4296,6 +4310,7 @@ the end of the file.
<!-- YAML
added: v10.0.0
-->
+
* `data` {string|Buffer|Uint8Array}
* `options` {Object|string}
* `encoding` {string|null} **Default:** `'utf8'`
@@ -4832,6 +4847,7 @@ Change the file system timestamps of the object referenced by `path` then
resolves the `Promise` with no arguments upon success.
The `atime` and `mtime` arguments follow these rules:
+
- Values can be either numbers representing Unix epoch time, `Date`s, or a
numeric string like `'123456789.0'`.
- If the value can not be converted to a number, or is `NaN`, `Infinity` or
diff --git a/doc/api/http.md b/doc/api/http.md
index ed68a7be0d..62e9d6e4dc 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -1929,6 +1929,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/15752
description: The `options` argument is supported now.
-->
+
* `options` {Object}
* `IncomingMessage` {http.IncomingMessage} Specifies the `IncomingMessage`
class to be used. Useful for extending the original `IncomingMessage`.
diff --git a/doc/api/http2.md b/doc/api/http2.md
index 293aa71f3e..6a9f0c8300 100644
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@@ -1026,6 +1026,7 @@ the `'aborted'` event will have been emitted.
<!-- YAML
added: v11.2.0
-->
+
* {number}
This property shows the number of characters currently buffered to be written.
@@ -1751,6 +1752,7 @@ a given number of milliseconds set using `http2server.setTimeout()`.
<!-- YAML
added: v8.4.0
-->
+
* `callback` {Function}
Stops the server from establishing new sessions. This does not prevent new
@@ -1900,6 +1902,7 @@ the connection is terminated. See the [Compatibility API][].
<!-- YAML
added: v8.4.0
-->
+
* `callback` {Function}
Stops the server from establishing new sessions. This does not prevent new
@@ -2324,17 +2327,18 @@ means that normal JavaScript object methods such as
not work.
For incoming headers:
+
* The `:status` header is converted to `number`.
* Duplicates of `:status`, `:method`, `:authority`, `:scheme`, `:path`,
-`:protocol`, `age`, `authorization`, `access-control-allow-credentials`,
-`access-control-max-age`, `access-control-request-method`, `content-encoding`,
-`content-language`, `content-length`, `content-location`, `content-md5`,
-`content-range`, `content-type`, `date`, `dnt`, `etag`, `expires`, `from`,
-`if-match`, `if-modified-since`, `if-none-match`, `if-range`,
-`if-unmodified-since`, `last-modified`, `location`, `max-forwards`,
-`proxy-authorization`, `range`, `referer`,`retry-after`, `tk`,
-`upgrade-insecure-requests`, `user-agent` or `x-content-type-options` are
-discarded.
+ `:protocol`, `age`, `authorization`, `access-control-allow-credentials`,
+ `access-control-max-age`, `access-control-request-method`, `content-encoding`,
+ `content-language`, `content-length`, `content-location`, `content-md5`,
+ `content-range`, `content-type`, `date`, `dnt`, `etag`, `expires`, `from`,
+ `if-match`, `if-modified-since`, `if-none-match`, `if-range`,
+ `if-unmodified-since`, `last-modified`, `location`, `max-forwards`,
+ `proxy-authorization`, `range`, `referer`,`retry-after`, `tk`,
+ `upgrade-insecure-requests`, `user-agent` or `x-content-type-options` are
+ discarded.
* `set-cookie` is always an array. Duplicates are added to the array.
* For duplicate `cookie` headers, the values are joined together with '; '.
* For all other headers, the values are joined together with ', '.
@@ -3386,6 +3390,7 @@ will result in a [`TypeError`][] being thrown.
<!-- YAML
added: v8.4.0
-->
+
* `headers` {HTTP/2 Headers Object} An object describing the headers
* `callback` {Function} Called once `http2stream.pushStream()` is finished,
or either when the attempt to create the pushed `Http2Stream` has failed or
diff --git a/doc/api/https.md b/doc/api/https.md
index d396c8a70d..7f188ea8a3 100644
--- a/doc/api/https.md
+++ b/doc/api/https.md
@@ -31,6 +31,7 @@ changes:
description: do not automatically set servername if the target host was
specified using an IP address.
-->
+
* `options` {Object} Set of configurable options to set on the agent.
Can have the same fields as for [`http.Agent(options)`][], and
* `maxCachedSessions` {number} maximum number of TLS cached sessions.
@@ -57,6 +58,7 @@ See [`http.Server`][] for more information.
<!-- YAML
added: v0.1.90
-->
+
* `callback` {Function}
* Returns: {https.Server}
@@ -66,6 +68,7 @@ See [`server.close()`][`http.close()`] from the HTTP module for details.
<!-- YAML
added: v11.3.0
-->
+
- {number} **Default:** `40000`
See [`http.Server#headersTimeout`][].
@@ -85,6 +88,7 @@ See [`http.Server#maxHeadersCount`][].
<!-- YAML
added: v0.11.2
-->
+
* `msecs` {number} **Default:** `120000` (2 minutes)
* `callback` {Function}
* Returns: {https.Server}
@@ -95,6 +99,7 @@ See [`http.Server#setTimeout()`][].
<!-- YAML
added: v0.11.2
-->
+
- {number} **Default:** `120000` (2 minutes)
See [`http.Server#timeout`][].
@@ -103,6 +108,7 @@ See [`http.Server#timeout`][].
<!-- YAML
added: v8.0.0
-->
+
- {number} **Default:** `5000` (5 seconds)
See [`http.Server#keepAliveTimeout`][].
@@ -111,6 +117,7 @@ See [`http.Server#keepAliveTimeout`][].
<!-- YAML
added: v0.3.4
-->
+
* `options` {Object} Accepts `options` from [`tls.createServer()`][],
[`tls.createSecureContext()`][] and [`http.createServer()`][].
* `requestListener` {Function} A listener to be added to the `'request'` event.
@@ -162,6 +169,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/10638
description: The `options` parameter can be a WHATWG `URL` object.
-->
+
* `url` {string | URL}
* `options` {Object | string | URL} Accepts the same `options` as
[`https.request()`][], with the `method` always set to `GET`.
@@ -212,6 +220,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/10638
description: The `options` parameter can be a WHATWG `URL` object.
-->
+
* `url` {string | URL}
* `options` {Object | string | URL} Accepts all `options` from
[`http.request()`][], with some differences in default values:
diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index a62fbbf186..ae0bed2af3 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -24,6 +24,7 @@ APIs exposed by N-API are generally used to create and manipulate
JavaScript values. Concepts and operations generally map to ideas specified
in the ECMA-262 Language Specification. The APIs have the following
properties:
+
- All N-API calls return a status code of type `napi_status`. This
status indicates whether the API call succeeded or failed.
- The API's return value is passed via an out parameter.
@@ -86,6 +87,7 @@ Although N-API provides an ABI stability guarantee, other parts of Node.js do
not, and any external libraries used from the addon may not. In particular,
none of the following APIs provide an ABI stability guarantee across major
versions:
+
* the Node.js C++ APIs available via any of
```C++
@@ -1374,6 +1376,7 @@ NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
the `napi_value passed` in or out of these methods is a handle to the
object to which the reference is related.
+
- `[in] env`: The environment that the API is invoked under.
- `[in] ref`: `napi_ref` for which we requesting the corresponding `Object`.
- `[out] result`: The `napi_value` for the `Object` referenced by the
@@ -1559,6 +1562,7 @@ Some of these types are documented under
of the [ECMAScript Language Specification][].
Fundamentally, these APIs are used to do one of the following:
+
1. Create a new JavaScript object
2. Convert from a primitive C type to an N-API value
3. Convert from N-API value to a primitive C type
@@ -2836,6 +2840,7 @@ values. Some of these operations are documented under
of the [ECMAScript Language Specification][].
These APIs support doing one of the following:
+
1. Coerce JavaScript values to specific JavaScript types (such as `Number` or
`String`).
2. Check the type of a JavaScript value.
@@ -2948,6 +2953,7 @@ napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)
- `[out] result`: The type of the JavaScript value.
Returns `napi_ok` if the API succeeded.
+
- `napi_invalid_arg` if the type of `value` is not a known ECMAScript type and
`value` is not an External value.
@@ -3147,10 +3153,11 @@ objects. Some of these types are documented under
Properties in JavaScript are represented as a tuple of a key and a value.
Fundamentally, all property keys in N-API can be represented in one of the
following forms:
+
- Named: a simple UTF8-encoded string
- Integer-Indexed: an index value represented by `uint32_t`
- JavaScript value: these are represented in N-API by `napi_value`. This can
-be a `napi_value` representing a `String`, `Number`, or `Symbol`.
+ be a `napi_value` representing a `String`, `Number`, or `Symbol`.
N-API values are represented by the type `napi_value`.
Any N-API call that requires a JavaScript value takes in a `napi_value`.
@@ -3691,6 +3698,7 @@ the `napi_callback` type. When the JavaScript VM calls back to
native code, the `napi_callback` function provided is invoked. The APIs
documented in this section allow the callback function to do the
following:
+
- Get information about the context in which the callback was invoked.
- Get the arguments passed into the callback.
- Return a `napi_value` back from the callback.
@@ -4209,7 +4217,8 @@ Returns `napi_ok` if the API succeeded.
Adds a `napi_finalize` callback which will be called when the JavaScript object
in `js_object` is ready for garbage collection. This API is similar to
-`napi_wrap()` except that
+`napi_wrap()` except that:
+
* the native data cannot be retrieved later using `napi_unwrap()`,
* nor can it be removed later using `napi_remove_wrap()`, and
* the API can be called multiple times with different data items in order to
diff --git a/doc/api/net.md b/doc/api/net.md
index b5cbd3e90e..b08553bdf2 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -321,6 +321,7 @@ Start an [IPC][] server listening for connections on the given `path`.
<!-- YAML
added: v0.1.90
-->
+
* `port` {number}
* `host` {string}
* `backlog` {number} Common parameter of [`server.listen()`][] functions.
@@ -942,6 +943,7 @@ Possible signatures:
<!-- YAML
added: v0.7.0
-->
+
* `options` {Object}
* `connectListener` {Function}
@@ -952,6 +954,7 @@ Alias to
<!-- YAML
added: v0.1.90
-->
+
* `path` {string}
* `connectListener` {Function}
@@ -962,6 +965,7 @@ Alias to
<!-- YAML
added: v0.1.90
-->
+
* `port` {number}
* `host` {string}
* `connectListener` {Function}
diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md
index b382ae2332..d6ae1946c4 100644
--- a/doc/api/perf_hooks.md
+++ b/doc/api/perf_hooks.md
@@ -320,6 +320,7 @@ Disconnects the `PerformanceObserver` instance from all notifications.
<!-- YAML
added: v8.5.0
-->
+
* `options` {Object}
* `entryTypes` {string[]} An array of strings identifying the types of
`PerformanceEntry` instances the observer is interested in. If not
diff --git a/doc/api/process.md b/doc/api/process.md
index 7922c36c28..0c2f61d16e 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -765,6 +765,7 @@ console.log(`Current directory: ${process.cwd()}`);
<!-- YAML
added: v0.7.2
-->
+
* {number}
The port used by Node.js's debugger when enabled.
@@ -2057,6 +2058,7 @@ This feature is not available in [`Worker`][] threads.
<!-- YAML
added: v0.1.28
-->
+
* `id` {integer | string}
The `process.setuid(id)` method sets the user identity of the process. (See
diff --git a/doc/api/querystring.md b/doc/api/querystring.md
index 74bca27d33..86885535af 100644
--- a/doc/api/querystring.md
+++ b/doc/api/querystring.md
@@ -144,6 +144,7 @@ querystring.stringify({ w: '中文', foo: 'bar' }, null, null,
<!-- YAML
added: v0.1.25
-->
+
* `str` {string}
The `querystring.unescape()` method performs decoding of URL percent-encoded
diff --git a/doc/api/stream.md b/doc/api/stream.md
index 73659524ec..5349b28a77 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1444,6 +1444,7 @@ Examples of `Transform` streams include:
<!-- YAML
added: v8.0.0
-->
+
* `error` {Error}
Destroy the stream, and optionally emit an `'error'` event. After this call, the
diff --git a/doc/api/tls.md b/doc/api/tls.md
index 90b377f5b5..936cc1c027 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -316,6 +316,7 @@ the default configuration. If these clients _must_ be supported, the
on the format, see the OpenSSL [cipher list format][] documentation.
There are only 5 TLSv1.3 cipher suites:
+
- `'TLS_AES_256_GCM_SHA384'`
- `'TLS_CHACHA20_POLY1305_SHA256'`
- `'TLS_AES_128_GCM_SHA256'`
@@ -931,6 +932,7 @@ The certificate may contain information about the public key, depending on
the key type.
For RSA keys, the following properties may be defined:
+
* `bits` {number} The RSA bit size. Example: `1024`.
* `exponent` {string} The RSA exponent, as a string in hexadecimal number
notation. Example: `'0x010001'`.
@@ -939,6 +941,7 @@ For RSA keys, the following properties may be defined:
* `pubkey` {Buffer} The public key.
For EC keys, the following properties may be defined:
+
* `pubkey` {Buffer} The public key.
* `bits` {number} The key size in bits. Example: `256`.
* `asn1Curve` {string} (Optional) The ASN.1 name of the OID of the elliptic
diff --git a/doc/api/tty.md b/doc/api/tty.md
index 7111f2d228..f2de746667 100644
--- a/doc/api/tty.md
+++ b/doc/api/tty.md
@@ -178,6 +178,7 @@ added: v9.9.0
* Returns: {number}
Returns:
+
* `1` for 2,
* `4` for 16,
* `8` for 256,
@@ -205,6 +206,7 @@ Disabling color support is also possible by using the `NO_COLOR` and
<!-- YAML
added: v0.7.7
-->
+
* Returns: {number[]}
`writeStream.getWindowSize()` returns the size of the [TTY](tty.html)
diff --git a/doc/api/util.md b/doc/api/util.md
index 982d3ebe53..8fab6baaaf 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -1745,6 +1745,7 @@ applications and modules should be updated to find alternative approaches.
added: v0.7.5
deprecated: v6.0.0
-->
+
* `target` {Object}
* `source` {Object}
diff --git a/doc/api/v8.md b/doc/api/v8.md
index 3c4b20df78..82d29712d5 100644
--- a/doc/api/v8.md
+++ b/doc/api/v8.md
@@ -41,6 +41,7 @@ heap space can be guaranteed as the statistics are provided via the V8
next.
The value returned is an array of objects containing the following properties:
+
* `space_name` {string}
* `space_size` {number}
* `space_used_size` {number}
@@ -191,6 +192,7 @@ Returns an object with the following properties:
<!-- YAML
added: v1.0.0
-->
+
* `flags` {string}
The `v8.setFlagsFromString()` method can be used to programmatically set
diff --git a/doc/api/vm.md b/doc/api/vm.md
index c657aeb07d..cd0d3077e4 100644
--- a/doc/api/vm.md
+++ b/doc/api/vm.md
@@ -666,6 +666,7 @@ The URL of the current module, as set in the constructor.
<!-- YAML
added: v10.10.0
-->
+
* `code` {string} The body of the function to compile.
* `params` {string[]} An array of strings containing all parameters for the
function.
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
index fa409627eb..60170be54c 100644
--- a/doc/api/worker_threads.md
+++ b/doc/api/worker_threads.md
@@ -303,6 +303,7 @@ Sends a JavaScript value to the receiving side of this channel.
the [HTML structured clone algorithm][].
In particular, the significant differences to `JSON` are:
+
- `value` may contain circular references.
- `value` may contain instances of builtin JS types such as `RegExp`s,
`BigInt`s, `Map`s, `Set`s, etc.
diff --git a/doc/api/zlib.md b/doc/api/zlib.md
index 19a0f7232e..a2250ea3f6 100644
--- a/doc/api/zlib.md
+++ b/doc/api/zlib.md
@@ -732,6 +732,7 @@ without a callback.
<!-- YAML
added: v11.7.0
-->
+
* `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string}
* `options` {brotli options}
* `callback` {Function}
@@ -740,6 +741,7 @@ added: v11.7.0
<!-- YAML
added: v11.7.0
-->
+
* `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string}
* `options` {brotli options}
@@ -749,6 +751,7 @@ Compress a chunk of data with [`BrotliCompress`][].
<!-- YAML
added: v11.7.0
-->
+
* `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string}
* `options` {brotli options}
* `callback` {Function}
@@ -757,6 +760,7 @@ added: v11.7.0
<!-- YAML
added: v11.7.0
-->
+
* `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string}
* `options` {brotli options}
@@ -776,6 +780,7 @@ changes:
pr-url: https://github.com/nodejs/node/pull/12001
description: The `buffer` parameter can be an `Uint8Array` now.
-->
+
* `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string}
* `options` {zlib options}
* `callback` {Function}
diff --git a/doc/changelogs/CHANGELOG_V4.md b/doc/changelogs/CHANGELOG_V4.md
index 31a5f4ce9f..a585aee314 100644
--- a/doc/changelogs/CHANGELOG_V4.md
+++ b/doc/changelogs/CHANGELOG_V4.md
@@ -1938,6 +1938,7 @@ This LTS release comes with 113 commits, 56 of which are doc related,
and 7 which are benchmark related.
### Notable Changes
+
* **build**:
- Updated Logos for the OSX + Windows installers
- (Rod Vagg) [#5401](https://github.com/nodejs/node/pull/5401)
diff --git a/doc/changelogs/CHANGELOG_V5.md b/doc/changelogs/CHANGELOG_V5.md
index 5fb784162f..72ad119c11 100644
--- a/doc/changelogs/CHANGELOG_V5.md
+++ b/doc/changelogs/CHANGELOG_V5.md
@@ -922,7 +922,7 @@ This is an important security release. All Node.js users should consult the secu
- **http**: improves expect header handling (Daniel Sellers) [#4501](https://github.com/nodejs/node/pull/4501)
- **node**: allow preload modules with -i (Evan Lucas) [#4696](https://github.com/nodejs/node/pull/4696)
- **v8,src**: expose statistics about heap spaces (`v8.getHeapSpaceStatistics()`) (Ben Ripkens) [#4463](https://github.com/nodejs/node/pull/4463)
-* Minor performance improvements:
+- Minor performance improvements:
- **lib**: Use arrow functions instead of bind where possible (Minwoo Jung) [#3622](https://github.com/nodejs/node/pull/3622).
- (Mistakenly missing from v5.4.0)
- **module**: cache stat() results more aggressively (Ben Noordhuis) [#4575](https://github.com/nodejs/node/pull/4575)
diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md
index c452b49f83..3bb2b2d12f 100644
--- a/doc/guides/contributing/pull-requests.md
+++ b/doc/guides/contributing/pull-requests.md
@@ -105,6 +105,7 @@ $ git checkout -b my-branch -t upstream/master
The vast majority of Pull Requests opened against the `nodejs/node`
repository includes changes to one or more of the following:
+
- the C/C++ code contained in the `src` directory
- the JavaScript code contained in the `lib` directory
- the documentation in `doc/api`
diff --git a/doc/releases.md b/doc/releases.md
index 4e8b24830e..da4a296960 100644
--- a/doc/releases.md
+++ b/doc/releases.md
@@ -144,6 +144,7 @@ appropriate PRs and commits into it.
Go through PRs with the label `vN.x`. e.g. [PRs with the `v8.x` label](https://github.com/nodejs/node/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Av8.x).
For each PR:
+
- Run or check that there is a passing CI.
- Check approvals (you can approve yourself).
- Check that the commit metadata was not changed from the `master` commit.
@@ -172,6 +173,7 @@ Previous release commits and version bumps do not need to be
cherry-picked.
Carefully review the list of commits:
+
- Checking for errors (incorrect `PR-URL`)
- Checking semver status - Commits labeled as `semver-minor` or `semver-major`
should only be cherry-picked when appropriate for the type of release being