From 2a5340144c90631608f1cf742b04e701a561fb2a Mon Sep 17 00:00:00 2001 From: Nick Schonning Date: Fri, 6 Sep 2019 01:42:22 -0400 Subject: [PATCH] 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 Reviewed-By: David Carlier Reviewed-By: Colin Ihrig Reviewed-By: Trivikram Kamat --- COLLABORATOR_GUIDE.md | 4 +- CPP_STYLE_GUIDE.md | 2 + doc/STYLE_GUIDE.md | 1 + doc/api/addons.md | 3 + doc/api/assert.md | 18 ++++++ doc/api/console.md | 18 ++++++ doc/api/crypto.md | 75 ++++++++++++++++++++++++ doc/api/dgram.md | 2 + doc/api/dns.md | 31 ++++++++++ doc/api/esm.md | 8 +++ doc/api/events.md | 11 +++- doc/api/fs.md | 16 +++++ doc/api/http.md | 1 + doc/api/http2.md | 23 +++++--- doc/api/https.md | 9 +++ doc/api/n-api.md | 13 +++- doc/api/net.md | 4 ++ doc/api/perf_hooks.md | 1 + doc/api/process.md | 2 + doc/api/querystring.md | 1 + doc/api/stream.md | 1 + doc/api/tls.md | 3 + doc/api/tty.md | 2 + doc/api/util.md | 1 + doc/api/v8.md | 2 + doc/api/vm.md | 1 + doc/api/worker_threads.md | 1 + doc/api/zlib.md | 5 ++ doc/changelogs/CHANGELOG_V4.md | 1 + doc/changelogs/CHANGELOG_V5.md | 2 +- doc/guides/contributing/pull-requests.md | 1 + doc/releases.md | 2 + 32 files changed, 249 insertions(+), 16 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index d8e0d22fd8f705..b3dbd05756c23c 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][]. - - -* Change the original commit message to include metadata. (The +* 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 07733db96ca89e..c3fe1e840746cb 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 15ae647044f4e3..3cc162f6dc8300 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -56,6 +56,7 @@ * NOT OK: Javascript, Google's v8 + * 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 59d708a71f7d1f..81bd8b5bacc68e 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 exports`, * `Local module`, and * `Local 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` 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 6057ba5c2afff1..db222580c30235 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -19,6 +19,7 @@ will be instances of the `AssertionError` class. + * `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()); + * `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 + * `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( + * `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 + * `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`. + * `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); + * `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 c03e7b82331ba8..b9a5ea30359054 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()`][]. + * `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. + * `data` {any} * `...args` {any} @@ -323,6 +328,7 @@ Decreases indentation of subsequent lines by two spaces. + * `data` {any} * `...args` {any} @@ -332,6 +338,7 @@ The `console.info()` function is an alias for [`console.log()`][]. + * `data` {any} * `...args` {any} @@ -391,6 +398,7 @@ console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }], ['a']); + * `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'); + * `label` {string} **Default:** `'default'` * `...data` {any} @@ -442,6 +452,7 @@ console.timeEnd('process'); + * `message` {any} * `...args` {any} @@ -468,6 +479,7 @@ console.trace('Show me'); + * `data` {any} * `...args` {any} @@ -482,6 +494,7 @@ not display anything unless used in conjunction with the [inspector][] + * `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 + * `label` {string} This method does not display anything unless used in the inspector. The @@ -510,6 +524,7 @@ console.profileEnd('MyLabel'); + * `label` {string} This method does not display anything unless used in the inspector. Stops the @@ -524,6 +539,7 @@ stopped. + * `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 + * `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 + * `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 dbef108f898808..137d6e0508a33e 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 + * `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')); + * `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); + * `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(); + * `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')); + * `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); + * `spkac` {Buffer | TypedArray | DataView} * Returns: {boolean} `true` if the given `spkac` data structure is valid, `false` otherwise. @@ -263,6 +269,7 @@ console.log(encrypted); + * `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. + * `buffer` {Buffer} * `options` {Object} [`stream.transform` options][] - `plaintextLength` {number} @@ -295,6 +303,7 @@ The `cipher.setAAD()` method must be called before [`cipher.update()`][]. + * 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. + * `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); + * `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 + * `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')); + * `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 + * `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 + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} @@ -633,6 +652,7 @@ returned; otherwise a [`Buffer`][] is returned. + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} @@ -644,6 +664,7 @@ returned; otherwise a [`Buffer`][] is returned. + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} @@ -655,6 +676,7 @@ string is returned; otherwise a [`Buffer`][] is returned. + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} @@ -666,6 +688,7 @@ string is returned; otherwise a [`Buffer`][] is returned. + * `privateKey` {string | Buffer | TypedArray | DataView} * `encoding` {string} The [encoding][] of the `privateKey` string. @@ -678,6 +701,7 @@ to be a [`Buffer`][], `TypedArray`, or `DataView`. + * `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. + * `encoding` {string} The [encoding][] of the return value. * `format` {string} **Default:** `'uncompressed'` * Returns: {Buffer | string} @@ -865,6 +891,7 @@ is returned. + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} The EC Diffie-Hellman in the specified `encoding`. @@ -875,6 +902,7 @@ returned. + * `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. + * `privateKey` {string | Buffer | TypedArray | DataView} * `encoding` {string} The [encoding][] of the `privateKey` string. @@ -1016,6 +1045,7 @@ console.log(hash.digest('hex')); + * `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')); + * `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. + * `options`: {Object} * Returns: {string | Buffer} @@ -1241,6 +1276,7 @@ PKCS#1 and SEC1 encryption. + * {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. + * {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. + * 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. + * `primeLength` {number} * `generator` {number | string | Buffer | TypedArray | DataView} **Default:** `2` @@ -1786,6 +1832,7 @@ An alias for [`crypto.getDiffieHellman()`][] + * `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', () => { + * `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. + * `key` {Buffer} * Returns: {KeyObject} @@ -1954,6 +2006,7 @@ encryption or `Hmac`. + * `algorithm` {string} * `options` {Object} [`stream.Writable` options][] * Returns: {Sign} @@ -1972,6 +2025,7 @@ algorithm names. + * `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. + * 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', ...] + * 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', ...] + * `groupName` {string} * Returns: {DiffieHellman} @@ -2169,6 +2228,7 @@ console.log(aliceSecret === bobSecret); + * Returns: {boolean} `true` if and only if a FIPS compliant crypto provider is currently in use. @@ -2176,6 +2236,7 @@ added: v10.0.0 + * 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' + * `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. + * `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. + * `algorithm` {string | null | undefined} * `data` {Buffer | TypedArray | DataView} * `key` {Object | string | Buffer | KeyObject} @@ -2793,6 +2866,7 @@ additional properties can be passed: + * `a` {Buffer | TypedArray | DataView} * `b` {Buffer | TypedArray | DataView} * Returns: {boolean} @@ -2814,6 +2888,7 @@ not introduce timing vulnerabilities. + * `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 f4ae367527748b..38d9492be8790f 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({ + * `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 43f78af7c7e0fd..f8b051b884289d 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). + * `address` {string} * `port` {number} * `callback` {Function} @@ -252,6 +254,7 @@ If this method is invoked as its [`util.promisify()`][]ed version, it returns a + * `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()`][], + * `hostname` {string} * `callback` {Function} - `err` {Error} @@ -394,6 +400,7 @@ will contain an array of canonical name records available for the `hostname` + * `hostname` {string} * `callback` {Function} - `err` {Error} @@ -408,6 +415,7 @@ property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`). + * `hostname` {string} * `callback` {Function} - `err` {Error} @@ -440,6 +448,7 @@ function will contain an array of objects with the following properties: + * `hostname` {string} * `callback` {Function} - `err` {Error} @@ -454,6 +463,7 @@ contain an array of name server records available for `hostname` + * `hostname` {string} * `callback` {Function} - `err` {Error} @@ -467,6 +477,7 @@ be an array of strings containing the reply records. + * `hostname` {string} * `callback` {Function} - `err` {Error} @@ -501,6 +512,7 @@ be an object with the following properties: + * `hostname` {string} * `callback` {Function} - `err` {Error} @@ -529,6 +541,7 @@ be an array of objects with the following properties: + * `hostname` {string} * `callback` {Function} - `err` {Error} @@ -545,6 +558,7 @@ treated separately. + * `ip` {string} * `callback` {Function} - `err` {Error} @@ -560,6 +574,7 @@ one of the [DNS error codes][]. + * `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. + * `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) => { + * `address` {string} * `port` {number} @@ -757,6 +774,7 @@ dnsPromises.lookupService('127.0.0.1', 22).then((result) => { + * `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). + * `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']`). + * `hostname` {string} Hostname to resolve. * `options` {Object} - `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. @@ -816,6 +836,7 @@ addresses. + * `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: + * `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']`). + * `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. + * `hostname` {string} Uses the DNS protocol to resolve regular expression based records (`NAPTR` @@ -910,6 +934,7 @@ of objects with the following properties: + * `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. + * `hostname` {string} Uses the DNS protocol to resolve pointer records (`PTR` records) for the @@ -931,6 +957,7 @@ containing the reply records. + * `hostname` {string} Uses the DNS protocol to resolve a start of authority record (`SOA` record) for @@ -962,6 +989,7 @@ following properties: + * `hostname` {string} Uses the DNS protocol to resolve service records (`SRV` records) for the @@ -987,6 +1015,7 @@ the following properties: + * `hostname` {string} Uses the DNS protocol to resolve text queries (`TXT` records) for the @@ -1000,6 +1029,7 @@ treated separately. + * `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). + * `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 1d6ae5d5998e24..114e3319e1bfab 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. Resolver algorithm specification **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 021c6b05989dad..3b92a04ca582a2 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'`. + * `eventName` {string|symbol} * `listener` {Function} @@ -297,8 +299,9 @@ Alias for `emitter.on(eventName, listener)`. + * `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. + * `eventName` {string|symbol} * Returns: {EventEmitter} @@ -551,6 +556,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained. + * `eventName` {string|symbol} * `listener` {Function} * Returns: {EventEmitter} @@ -640,6 +646,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained. + * `n` {integer} * Returns: {EventEmitter} @@ -656,6 +663,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained. + * `eventName` {string|symbol} * Returns: {Function[]} @@ -690,6 +698,7 @@ emitter.emit('log'); + * `emitter` {EventEmitter} * `name` {string} * Returns: {Promise} diff --git a/doc/api/fs.md b/doc/api/fs.md index b1414b6e54a369..8077c533f854d2 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. + * `data` {string|Buffer} * `options` {Object|string} * `encoding` {string|null} **Default:** `'utf8'` @@ -4010,6 +4014,7 @@ The `FileHandle` must have been opened for appending. + * `mode` {integer} * Returns: {Promise} @@ -4020,6 +4025,7 @@ arguments upon success. + * `uid` {integer} * `gid` {integer} * Returns: {Promise} @@ -4055,6 +4061,7 @@ async function openAndClose() { + * Returns: {Promise} Asynchronous fdatasync(2). The `Promise` is resolved with no arguments upon @@ -4071,6 +4078,7 @@ 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. + * `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. + * Returns: {Promise} Asynchronous fsync(2). The `Promise` is resolved with no arguments upon @@ -4152,6 +4163,7 @@ success. + * `len` {integer} **Default:** `0` * Returns: {Promise} @@ -4220,6 +4232,7 @@ The last three bytes are null bytes (`'\0'`), to compensate the over-truncation. + * `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 + * `buffer` {Buffer|Uint8Array} * `offset` {integer} * `length` {integer} @@ -4296,6 +4310,7 @@ the end of the file. + * `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 c76f3eee393c12..998d9c219fddf9 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -1921,6 +1921,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 a765aa506d5300..8ddf3b989df905 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1026,6 +1026,7 @@ the `'aborted'` event will have been emitted. + * {number} This property shows the number of characters currently buffered to be written. @@ -1750,6 +1751,7 @@ flag. + * `callback` {Function} Stops the server from establishing new sessions. This does not prevent new @@ -1898,6 +1900,7 @@ the connection is terminated. See the [Compatibility API][]. + * `callback` {Function} Stops the server from establishing new sessions. This does not prevent new @@ -2325,17 +2328,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 ', '. @@ -3396,6 +3400,7 @@ will result in a [`TypeError`][] being thrown. + * `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 d396c8a70dafad..7f188ea8a3ff87 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. + * `callback` {Function} * Returns: {https.Server} @@ -66,6 +68,7 @@ See [`server.close()`][`http.close()`] from the HTTP module for details. + - {number} **Default:** `40000` See [`http.Server#headersTimeout`][]. @@ -85,6 +88,7 @@ See [`http.Server#maxHeadersCount`][]. + * `msecs` {number} **Default:** `120000` (2 minutes) * `callback` {Function} * Returns: {https.Server} @@ -95,6 +99,7 @@ See [`http.Server#setTimeout()`][]. + - {number} **Default:** `120000` (2 minutes) See [`http.Server#timeout`][]. @@ -103,6 +108,7 @@ See [`http.Server#timeout`][]. + - {number} **Default:** `5000` (5 seconds) See [`http.Server#keepAliveTimeout`][]. @@ -111,6 +117,7 @@ See [`http.Server#keepAliveTimeout`][]. + * `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 e98342668b3a23..f9b9e99de9723a 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++ @@ -1373,6 +1375,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 @@ -1558,6 +1561,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 @@ -2835,6 +2839,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. @@ -2947,6 +2952,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. @@ -3146,10 +3152,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`. @@ -3690,6 +3697,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. @@ -4208,7 +4216,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 b5cbd3e90eef43..b08553bdf28aca 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`. + * `port` {number} * `host` {string} * `backlog` {number} Common parameter of [`server.listen()`][] functions. @@ -942,6 +943,7 @@ Possible signatures: + * `options` {Object} * `connectListener` {Function} @@ -952,6 +954,7 @@ Alias to + * `path` {string} * `connectListener` {Function} @@ -962,6 +965,7 @@ Alias to + * `port` {number} * `host` {string} * `connectListener` {Function} diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index b382ae2332a8fc..d6ae1946c4744e 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -320,6 +320,7 @@ Disconnects the `PerformanceObserver` instance from all notifications. + * `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 7922c36c2889bf..0c2f61d16e46de 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -765,6 +765,7 @@ console.log(`Current directory: ${process.cwd()}`); + * {number} The port used by Node.js's debugger when enabled. @@ -2057,6 +2058,7 @@ This feature is not available in [`Worker`][] threads. + * `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 74bca27d3306cf..86885535af1835 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -144,6 +144,7 @@ querystring.stringify({ w: '中文', foo: 'bar' }, null, null, + * `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 7fc4dd4452e433..6d64bfbf6c50f1 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1441,6 +1441,7 @@ Examples of `Transform` streams include: + * `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 90b377f5b5aa3c..936cc1c027996c 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 7111f2d228bd2b..f2de746667553f 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 + * 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 fdc4287fb7afc9..135ecc12bff98f 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -1726,6 +1726,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 3c4b20df780b7d..82d29712d5e498 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: + * `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 c657aeb07d2885..cd0d3077e47d74 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. + * `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 fa409627ebc472..60170be54cfb5a 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 19a0f7232e878c..a2250ea3f648c0 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -732,6 +732,7 @@ without a callback. + * `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} * `options` {brotli options} * `callback` {Function} @@ -740,6 +741,7 @@ added: v11.7.0 + * `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} * `options` {brotli options} @@ -749,6 +751,7 @@ Compress a chunk of data with [`BrotliCompress`][]. + * `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} * `options` {brotli options} * `callback` {Function} @@ -757,6 +760,7 @@ 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 31a5f4ce9fdfb5..a585aee31468e8 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 5fb784162f318d..72ad119c119c8b 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 c452b49f83db49..3bb2b2d12fe8e0 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 4e8b24830e0720..da4a29696028b8 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