doc: updates for better json generating

Semigradsky · richardlau · commit 9ddbe4523fb8 · 2024-03-25T19:26:21.000Z
PR-URL: #51592 Reviewed-By: Chemi Atlow <chemi@atlow.co.il> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com>
diff --git 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
@@ -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
@@ -1809,7 +1809,7 @@ added: v20.5.0
 
 * `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
@@ -3442,7 +3442,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.
 
@@ -6410,7 +6410,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}.
@@ -6468,7 +6468,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
@@ -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
@@ -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
@@ -1082,16 +1082,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
@@ -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
@@ -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
@@ -2676,10 +2676,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`.
@@ -2695,10 +2693,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.
 
@@ -3303,9 +3299,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
@@ -2834,8 +2834,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) =>{
@@ -2980,8 +2981,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
@@ -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: <Buffer|TypedArray|DataView>, identity: <string> }`
 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
@@ -915,8 +915,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
@@ -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
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md

-Original file line number
+Diff line change
 *`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`.