doc: updates for better json generating

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>

Author: Semigradsky

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';

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

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`.
 

doc/api/fs.md

@@ -3468,7 +3468,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.
 
@@ -6446,7 +6446,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}.
@@ -6504,7 +6504,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.

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.
 

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

doc/api/module.md

@@ -1009,16 +1009,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

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.
 

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}.
 

doc/api/stream.md

@@ -2647,10 +2647,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`.
@@ -2666,10 +2664,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.
 
@@ -3280,9 +3276,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`.

doc/api/test.md

@@ -2823,8 +2823,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) => {
@@ -2969,8 +2970,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

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.

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.

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.