From 4bcdd7763dbf88418935b49c5576550cbc400484 Mon Sep 17 00:00:00 2001 From: Dmitry Semigradsky Date: Wed, 14 Feb 2024 00:37:42 +0300 Subject: [PATCH] doc: updates for better json generating PR-URL: https://github.com/nodejs/node/pull/51592 Reviewed-By: Chemi Atlow Reviewed-By: Luigi Pinca Reviewed-By: Filip Skokan --- doc/api/assert.md | 12 ++++++------ doc/api/crypto.md | 10 +++++----- doc/api/events.md | 2 +- doc/api/fs.md | 6 +++--- doc/api/http.md | 8 ++++---- doc/api/inspector.md | 2 +- doc/api/module.md | 8 ++++---- doc/api/os.md | 4 ++-- doc/api/perf_hooks.md | 4 ++-- doc/api/stream.md | 13 ++++--------- doc/api/test.md | 10 ++++++---- doc/api/tls.md | 2 +- doc/api/url.md | 4 ++-- doc/api/util.md | 4 ++-- doc/api/webcrypto.md | 24 ++++++++++++------------ doc/api/worker_threads.md | 2 +- 16 files changed, 56 insertions(+), 59 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 3dfa47d0b4f680..92121c42f20a46 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -296,7 +296,7 @@ added: * `fn` {Function} **Default:** A no-op function. * `exact` {number} **Default:** `1`. -* Returns: {Function} that wraps `fn`. +* Returns: {Function} A function that wraps `fn`. The wrapper function is expected to be called exactly `exact` times. If the function has not been called exactly `exact` times when @@ -337,9 +337,9 @@ added: - v16.18.0 --> -* `fn` {Function}. +* `fn` {Function} -* Returns: {Array} with all the calls to a tracked function. +* Returns: {Array} An array with all the calls to a tracked function. * Object {Object} * `thisArg` {Object} @@ -380,8 +380,8 @@ added: - v12.19.0 --> -* Returns: {Array} of objects containing information about the wrapper functions - returned by [`tracker.calls()`][]. +* Returns: {Array} An array of objects containing information about the wrapper + functions returned by [`tracker.calls()`][]. * Object {Object} * `message` {string} * `actual` {number} The actual number of times the function was called. @@ -457,7 +457,7 @@ added: Reset calls of the call tracker. If a tracked function is passed as an argument, the calls will be reset for it. -If no arguments are passed, all tracked functions will be reset +If no arguments are passed, all tracked functions will be reset. ```mjs import assert from 'node:assert'; diff --git a/doc/api/crypto.md b/doc/api/crypto.md index deb85404249700..9d152f15dae326 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -570,7 +570,7 @@ added: v1.0.0 * `options` {Object} [`stream.transform` options][] * `plaintextLength` {number} * `encoding` {string} The string encoding to use when `buffer` is a string. -* Returns: {Cipher} for method chaining. +* Returns: {Cipher} The same `Cipher` instance for method chaining. When using an authenticated encryption mode (`GCM`, `CCM`, `OCB`, and `chacha20-poly1305` are @@ -590,7 +590,7 @@ added: v0.7.1 --> * `autoPadding` {boolean} **Default:** `true` -* Returns: {Cipher} for method chaining. +* Returns: {Cipher} The same `Cipher` instance for method chaining. When using block encryption algorithms, the `Cipher` class will automatically add padding to the input data to the appropriate block size. To disable the @@ -870,7 +870,7 @@ changes: * `options` {Object} [`stream.transform` options][] * `plaintextLength` {number} * `encoding` {string} String encoding to use when `buffer` is a string. -* Returns: {Decipher} for method chaining. +* Returns: {Decipher} The same Decipher for method chaining. When using an authenticated encryption mode (`GCM`, `CCM`, `OCB`, and `chacha20-poly1305` are @@ -905,7 +905,7 @@ changes: * `buffer` {string|Buffer|ArrayBuffer|TypedArray|DataView} * `encoding` {string} String encoding to use when `buffer` is a string. -* Returns: {Decipher} for method chaining. +* Returns: {Decipher} The same Decipher for method chaining. When using an authenticated encryption mode (`GCM`, `CCM`, `OCB`, and `chacha20-poly1305` are @@ -931,7 +931,7 @@ added: v0.7.1 --> * `autoPadding` {boolean} **Default:** `true` -* Returns: {Decipher} for method chaining. +* Returns: {Decipher} The same Decipher for method chaining. When data has been encrypted without standard block padding, calling `decipher.setAutoPadding(false)` will disable automatic padding to prevent diff --git a/doc/api/events.md b/doc/api/events.md index 19fccbce0c5a4b..c1b684cf3bd4e0 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -1815,7 +1815,7 @@ added: * `signal` {AbortSignal} * `listener` {Function|EventListener} -* Returns: {Disposable} that removes the `abort` listener. +* Returns: {Disposable} A Disposable that removes the `abort` listener. Listens once to the `abort` event on the provided `signal`. diff --git a/doc/api/fs.md b/doc/api/fs.md index 5cf806394f5362..4bd7da6de39030 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -3484,7 +3484,7 @@ added: v19.8.0 * `path` {string|Buffer|URL} * `options` {Object} * `type` {string} An optional mime type for the blob. -* Return: {Promise} containing {Blob} +* Returns: {Promise} Fulfills with a {Blob} upon success. Returns a {Blob} whose data is backed by the given file. @@ -6470,7 +6470,7 @@ The read-only path of this directory as was provided to [`fs.opendir()`][], added: v12.12.0 --> -* Returns: {Promise} containing {fs.Dirent|null} +* Returns: {Promise} Fulfills with a {fs.Dirent|null} Asynchronously read the next directory entry via readdir(3) as an {fs.Dirent}. @@ -6528,7 +6528,7 @@ included in the iteration results. added: v12.12.0 --> -* Returns: {AsyncIterator} of {fs.Dirent} +* Returns: {AsyncIterator} An AsyncIterator of {fs.Dirent} Asynchronously iterates over the directory until all entries have been read. Refer to the POSIX readdir(3) documentation for more detail. diff --git a/doc/api/http.md b/doc/api/http.md index d7b77f1a4c55ad..b138f22b2959ab 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -3090,7 +3090,7 @@ added: v0.4.0 --> * `name` {string} Name of header -* Returns {string | undefined} +* Returns: {string | undefined} Gets the value of the HTTP header with the given name. If that header is not set, the returned value will be `undefined`. @@ -3101,7 +3101,7 @@ set, the returned value will be `undefined`. added: v7.7.0 --> -* Returns {string\[]} +* Returns: {string\[]} Returns an array containing the unique names of the current outgoing headers. All names are lowercase. @@ -3140,7 +3140,7 @@ added: v7.7.0 --> * `name` {string} -* Returns {boolean} +* Returns: {boolean} Returns `true` if the header identified by `name` is currently set in the outgoing headers. The header name is case-insensitive. @@ -3360,7 +3360,7 @@ changes: * `chunk` {string|Buffer|Uint8Array} * `encoding` {string} **Default**: `utf8` * `callback` {Function} -* Returns {boolean} +* Returns: {boolean} Sends a chunk of the body. This method can be called multiple times. diff --git a/doc/api/inspector.md b/doc/api/inspector.md index 05178153ceb630..014581e7dc9c56 100644 --- a/doc/api/inspector.md +++ b/doc/api/inspector.md @@ -444,7 +444,7 @@ changes: **Default:** what was specified on the CLI. * `wait` {boolean} Block until a client has connected. Optional. **Default:** `false`. -* Returns: {Disposable} that calls [`inspector.close()`][]. +* Returns: {Disposable} A Disposable that calls [`inspector.close()`][]. Activate inspector on host and port. Equivalent to `node --inspect=[[host:]port]`, but can be done programmatically after node has diff --git a/doc/api/module.md b/doc/api/module.md index 7b63d70a5e38ec..e1097c1a48da3d 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -1020,16 +1020,16 @@ columnNumber)` * `lineNumber` {number} The 1-indexed line number of the call site in the generated source -* `columnOffset` {number} The 1-indexed column number +* `columnNumber` {number} The 1-indexed column number of the call site in the generated source * Returns: {Object} -Given a 1-indexed lineNumber and columnNumber from a call site in +Given a 1-indexed `lineNumber` and `columnNumber` from a call site in the generated source, find the corresponding call site location in the original source. -If the lineNumber and columnNumber provided are not found in any -source map, then an empty object is returned. Otherwise, the +If the `lineNumber` and `columnNumber` provided are not found in any +source map, then an empty object is returned. Otherwise, the returned object contains the following keys: * name: {string | undefined} The name of the range in the diff --git a/doc/api/os.md b/doc/api/os.md index 550ae7659de5f5..ce66dd25401609 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -250,7 +250,7 @@ added: - v16.18.0 --> -* Returns {string} +* Returns: {string} Returns the machine type as a string, such as `arm`, `arm64`, `aarch64`, `mips`, `mips64`, `ppc64`, `ppc64le`, `s390`, `s390x`, `i386`, `i686`, `x86_64`. @@ -483,7 +483,7 @@ added: - v12.17.0 --> -* Returns {string} +* Returns: {string} Returns a string identifying the kernel version. diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index 040b8eaa52027b..61e228113ef938 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -107,7 +107,7 @@ added: `eventLoopUtilization()`. * `utilization2` {Object} The result of a previous call to `eventLoopUtilization()` prior to `utilization1`. -* Returns {Object} +* Returns: {Object} * `idle` {number} * `active` {number} * `utilization` {number} @@ -1476,7 +1476,7 @@ added: **Default:** `Number.MAX_SAFE_INTEGER`. * `figures` {number} The number of accuracy digits. Must be a number between `1` and `5`. **Default:** `3`. -* Returns {RecordableHistogram} +* Returns: {RecordableHistogram} Returns a {RecordableHistogram}. diff --git a/doc/api/stream.md b/doc/api/stream.md index 93d7635a2679d0..d5b0044d65c2fd 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -2651,10 +2651,8 @@ changes: finished before the call to `finished(stream, cb)`. --> -* `stream` {Stream|ReadableStream|WritableStream} - -A readable and/or writable stream/webstream. - +* `stream` {Stream|ReadableStream|WritableStream} A readable and/or writable + stream/webstream. * `options` {Object} * `error` {boolean} If set to `false`, then a call to `emit('error', err)` is not treated as finished. **Default:** `true`. @@ -2670,10 +2668,8 @@ A readable and/or writable stream/webstream. listeners added by this function will also be removed. * `cleanup` {boolean} remove all registered stream listeners. **Default:** `false`. - * `callback` {Function} A callback function that takes an optional error argument. - * Returns: {Function} A cleanup function which removes all registered listeners. @@ -3286,9 +3282,8 @@ changes: --> * `signal` {AbortSignal} A signal representing possible cancellation -* `stream` {Stream|ReadableStream|WritableStream} - -A stream to attach a signal to. +* `stream` {Stream|ReadableStream|WritableStream} A stream to attach a signal + to. Attaches an AbortSignal to a readable or writeable stream. This lets code control stream destruction using an `AbortController`. diff --git a/doc/api/test.md b/doc/api/test.md index bb26b5eb8b92c5..d348061107ce11 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -2831,8 +2831,9 @@ added: - v16.17.0 --> -* {AbortSignal} Can be used to abort test subtasks when the test has been - aborted. +* Type: {AbortSignal} + +Can be used to abort test subtasks when the test has been aborted. ```js test('top level test', async (t) => { @@ -2977,8 +2978,9 @@ added: - v16.17.0 --> -* {AbortSignal} Can be used to abort test subtasks when the test has been - aborted. +* Type: {AbortSignal} + +Can be used to abort test subtasks when the test has been aborted. [TAP]: https://testanything.org/ [TTY]: tty.md diff --git a/doc/api/tls.md b/doc/api/tls.md index 200da769a20333..ccde27ab2c79d7 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1651,7 +1651,7 @@ changes: * hint: {string} optional message sent from the server to help client decide which identity to use during negotiation. Always `null` if TLS 1.3 is used. - * Returns: {Object} in the form + * Returns: {Object} An object in the form `{ psk: , identity: }` or `null` to stop the negotiation process. `psk` must be compatible with the selected cipher's digest. diff --git a/doc/api/url.md b/doc/api/url.md index 6412988d6103b6..ac07caa0405e3b 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -921,8 +921,8 @@ myURL.searchParams.forEach((value, name, searchParams) => { #### `urlSearchParams.get(name)` * `name` {string} -* Returns: {string} or `null` if there is no name-value pair with the given - `name`. +* Returns: {string | null} A string or `null` if there is no name-value pair + with the given `name`. Returns the value of the first name-value pair whose name is `name`. If there are no such pairs, `null` is returned. diff --git a/doc/api/util.md b/doc/api/util.md index e0ec21f3f67a39..ed05dfebaf5384 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -1275,8 +1275,8 @@ is the `name`, the second item of the array is the `value`. ### `mimeParams.get(name)` * `name` {string} -* Returns: {string} or `null` if there is no name-value pair with the given - `name`. +* Returns: {string | null} A string or `null` if there is no name-value pair + with the given `name`. Returns the value of the first name-value pair whose name is `name`. If there are no such pairs, `null` is returned. diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md index 07677b8f180de9..c7fb9ecf1953fc 100644 --- a/doc/api/webcrypto.md +++ b/doc/api/webcrypto.md @@ -555,7 +555,7 @@ added: v15.0.0 * `algorithm`: {RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams} * `key`: {CryptoKey} * `data`: {ArrayBuffer|TypedArray|DataView|Buffer} -* Returns: {Promise} containing {ArrayBuffer} +* Returns: {Promise} Fulfills with an {ArrayBuffer} Using the method and parameters specified in `algorithm` and the keying material provided by `key`, `subtle.decrypt()` attempts to decipher the @@ -586,7 +586,7 @@ changes: * `algorithm`: {AlgorithmIdentifier|EcdhKeyDeriveParams|HkdfParams|Pbkdf2Params} * `baseKey`: {CryptoKey} * `length`: {number|null} -* Returns: {Promise} containing {ArrayBuffer} +* Returns: {Promise} Fulfills with an {ArrayBuffer} @@ -631,7 +631,7 @@ changes: * `derivedKeyAlgorithm`: {HmacKeyGenParams|AesKeyGenParams} * `extractable`: {boolean} * `keyUsages`: {string\[]} See [Key usages][]. -* Returns: {Promise} containing {CryptoKey} +* Returns: {Promise} Fulfills with a {CryptoKey} @@ -660,7 +660,7 @@ added: v15.0.0 * `algorithm`: {string|Object} * `data`: {ArrayBuffer|TypedArray|DataView|Buffer} -* Returns: {Promise} containing {ArrayBuffer} +* Returns: {Promise} Fulfills with an {ArrayBuffer} Using the method identified by `algorithm`, `subtle.digest()` attempts to generate a digest of `data`. If successful, the returned promise is resolved @@ -685,7 +685,7 @@ added: v15.0.0 * `algorithm`: {RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams} * `key`: {CryptoKey} * `data`: {ArrayBuffer|TypedArray|DataView|Buffer} -* Returns: {Promise} containing {ArrayBuffer} +* Returns: {Promise} Fulfills with an {ArrayBuffer} Using the method and parameters specified by `algorithm` and the keying material provided by `key`, `subtle.encrypt()` attempts to encipher `data`. @@ -717,7 +717,7 @@ changes: * `format`: {string} Must be one of `'raw'`, `'pkcs8'`, `'spki'`, or `'jwk'`. * `key`: {CryptoKey} -* Returns: {Promise} containing {ArrayBuffer|Object}. +* Returns: {Promise} Fulfills with an {ArrayBuffer|Object}. Exports the given key into the specified format, if supported. @@ -762,7 +762,7 @@ added: v15.0.0 * `extractable`: {boolean} * `keyUsages`: {string\[]} See [Key usages][]. -* Returns: {Promise} containing {CryptoKey|CryptoKeyPair} +* Returns: {Promise} Fulfills with a {CryptoKey|CryptoKeyPair} Using the method and parameters provided in `algorithm`, `subtle.generateKey()` attempts to generate new keying material. Depending the method used, the method @@ -816,7 +816,7 @@ changes: * `extractable`: {boolean} * `keyUsages`: {string\[]} See [Key usages][]. -* Returns: {Promise} containing {CryptoKey} +* Returns: {Promise} Fulfills with a {CryptoKey} The `subtle.importKey()` method attempts to interpret the provided `keyData` as the given `format` to create a {CryptoKey} instance using the provided @@ -863,7 +863,7 @@ changes: * `algorithm`: {AlgorithmIdentifier|RsaPssParams|EcdsaParams|Ed448Params} * `key`: {CryptoKey} * `data`: {ArrayBuffer|TypedArray|DataView|Buffer} -* Returns: {Promise} containing {ArrayBuffer} +* Returns: {Promise} Fulfills with an {ArrayBuffer} @@ -900,7 +900,7 @@ added: v15.0.0 * `extractable`: {boolean} * `keyUsages`: {string\[]} See [Key usages][]. -* Returns: {Promise} containing {CryptoKey} +* Returns: {Promise} Fulfills with a {CryptoKey} In cryptography, "wrapping a key" refers to exporting and then encrypting the keying material. The `subtle.unwrapKey()` method attempts to decrypt a wrapped @@ -954,7 +954,7 @@ changes: * `key`: {CryptoKey} * `signature`: {ArrayBuffer|TypedArray|DataView|Buffer} * `data`: {ArrayBuffer|TypedArray|DataView|Buffer} -* Returns: {Promise} containing {boolean} +* Returns: {Promise} Fulfills with a {boolean} @@ -984,7 +984,7 @@ added: v15.0.0 * `key`: {CryptoKey} * `wrappingKey`: {CryptoKey} * `wrapAlgo`: {AlgorithmIdentifier|RsaOaepParams|AesCtrParams|AesCbcParams|AesGcmParams} -* Returns: {Promise} containing {ArrayBuffer} +* Returns: {Promise} Fulfills with an {ArrayBuffer} diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index ccbce9f96cc7eb..e4e842c6d21365 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -1165,7 +1165,7 @@ added: `eventLoopUtilization()`. * `utilization2` {Object} The result of a previous call to `eventLoopUtilization()` prior to `utilization1`. -* Returns {Object} +* Returns: {Object} * `idle` {number} * `active` {number} * `utilization` {number}