doc,tools: formalize, unify, codify default values

Backport-PR-URL: #19793
PR-URL: #19737
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

doc/STYLE_GUIDE.md

@@ -59,9 +59,9 @@
   * Use a capital letter after the "Note:" label.
   * Preferably, make the note a new paragraph for better visual distinction.
 * Function arguments or object properties should use the following format:
-  * <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`</code>
-  * E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`</code>
-  * The `type` should refer to a Node.js type or a [JavaScript type][]
+  * <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`.</code>
+  * E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.</code>
+  * The `type` should refer to a Node.js type or a [JavaScript type][].
 * Function returns should use the following format:
   * <code>* Returns: {type|type2} Optional description.</code>
   * E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code>

doc/api/assert.md

@@ -494,7 +494,7 @@ added: v0.1.21
 * `actual` {any}
 * `expected` {any}
 * `message` {any} **Default:** `'Failed'`
-* `operator` {string} **Default:** '!='
+* `operator` {string} **Default:** `'!='`
 * `stackStartFunction` {Function} **Default:** `assert.fail`
 
 Throws an `AssertionError`. If `message` is falsy, the error message is set as

doc/api/async_hooks.md

@@ -206,7 +206,7 @@ instance is destroyed.
 * `type` {string} The type of the async resource.
 * `triggerAsyncId` {number} The unique ID of the async resource in whose
   execution context this async resource was created.
-* `resource` {Object} Reference to the resource representing the async 
+* `resource` {Object} Reference to the resource representing the async
   operation, needs to be released during _destroy_.
 
 Called when a class is constructed that has the _possibility_ to emit an
@@ -283,10 +283,10 @@ The `TCPSERVERWRAP` is the server which receives the connections.
 
 The `TCPWRAP` is the new connection from the client. When a new
 connection is made the `TCPWrap` instance is immediately constructed. This
-happens outside of any JavaScript stack (side note: a `executionAsyncId()` of 
+happens outside of any JavaScript stack (side note: a `executionAsyncId()` of
 `0` means it's being executed from C++, with no JavaScript stack above it).
 With only that information, it would be impossible to link resources together in
-terms of what caused them to be created, so `triggerAsyncId` is given the task 
+terms of what caused them to be created, so `triggerAsyncId` is given the task
 of propagating what resource is responsible for the new resource's existence.
 
 ###### `resource`
@@ -582,7 +582,7 @@ the details of the V8 [PromiseHooks][] API.
 ## JavaScript Embedder API
 
 Library developers that handle their own asynchronous resources performing tasks
-like I/O, connection pooling, or managing callback queues may use the 
+like I/O, connection pooling, or managing callback queues may use the
 `AsyncWrap` JavaScript API so that all the appropriate callbacks are called.
 
 ### `class AsyncResource()`
@@ -640,8 +640,7 @@ asyncResource.emitAfter();
   * `requireManualDestroy` {boolean} Disables automatic `emitDestroy` when the
   object is garbage collected. This usually does not need to be set (even if
   `emitDestroy` is called manually), unless the resource's asyncId is retrieved
-  and the sensitive API's `emitDestroy` is called with it.
-  **Default:** `false`
+  and the sensitive API's `emitDestroy` is called with it. **Default:** `false`.
 
 Example usage:
 
@@ -728,7 +727,7 @@ never be called.
 
 #### `asyncResource.triggerAsyncId()`
 
-* Returns: {number} The same `triggerAsyncId` that is passed to the 
+* Returns: {number} The same `triggerAsyncId` that is passed to the
 `AsyncResource` constructor.
 
 [`after` callback]: #async_hooks_after_asyncid

doc/api/buffer.md

@@ -345,9 +345,9 @@ changes:
 
 * `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`],
   [`SharedArrayBuffer`] or the `.buffer` property of a [`TypedArray`].
-* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`
+* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
 * `length` {integer} Number of bytes to expose.
-  **Default:** `arrayBuffer.length - byteOffset`
+  **Default:** `arrayBuffer.length - byteOffset`.
 
 This creates a view of the [`ArrayBuffer`] or [`SharedArrayBuffer`] without
 copying the underlying memory. For example, when passed a reference to the
@@ -459,7 +459,7 @@ changes:
 > Use [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] instead.
 
 * `string` {string} String to encode.
-* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`
+* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`.
 
 Creates a new `Buffer` containing `string`. The `encoding` parameter identifies
 the character encoding of `string`.
@@ -488,9 +488,9 @@ changes:
 
 * `size` {integer} The desired length of the new `Buffer`.
 * `fill` {string|Buffer|integer} A value to pre-fill the new `Buffer` with.
-  **Default:** `0`
+  **Default:** `0`.
 * `encoding` {string} If `fill` is a string, this is its encoding.
-  **Default:** `'utf8'`
+  **Default:** `'utf8'`.
 
 Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the
 `Buffer` will be *zero-filled*.
@@ -646,7 +646,7 @@ changes:
 * `string` {string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer} A
   value to calculate the length of.
 * `encoding` {string} If `string` is a string, this is its encoding.
-  **Default:** `'utf8'`
+  **Default:** `'utf8'`.
 * Returns: {integer} The number of bytes contained within `string`.
 
 Returns the actual byte length of a string. This is not the same as
@@ -766,9 +766,9 @@ added: v5.10.0
 
 * `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`],
   [`SharedArrayBuffer`], or the `.buffer` property of a [`TypedArray`].
-* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`
+* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
 * `length` {integer} Number of bytes to expose.
-  **Default:** `arrayBuffer.length - byteOffset`
+  **Default:** `arrayBuffer.length - byteOffset`.
 
 This creates a view of the [`ArrayBuffer`] without copying the underlying
 memory. For example, when passed a reference to the `.buffer` property of a
@@ -837,7 +837,7 @@ added: v5.10.0
 -->
 
 * `string` {string} A string to encode.
-* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`
+* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`.
 
 Creates a new `Buffer` containing `string`. The `encoding` parameter identifies
 the character encoding of `string`.
@@ -976,13 +976,13 @@ changes:
 
 * `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to compare to.
 * `targetStart` {integer} The offset within `target` at which to begin
-  comparison. **Default:** `0`
+  comparison. **Default:** `0`.
 * `targetEnd` {integer} The offset with `target` at which to end comparison
-  (not inclusive). **Default:** `target.length`
+  (not inclusive). **Default:** `target.length`.
 * `sourceStart` {integer} The offset within `buf` at which to begin comparison.
-  **Default:** `0`
+  **Default:** `0`.
 * `sourceEnd` {integer} The offset within `buf` at which to end comparison
-  (not inclusive). **Default:** [`buf.length`]
+  (not inclusive). **Default:** [`buf.length`].
 * Returns: {integer}
 
 Compares `buf` with `target` and returns a number indicating whether `buf`
@@ -1039,11 +1039,11 @@ added: v0.1.90
 
 * `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to copy into.
 * `targetStart` {integer} The offset within `target` at which to begin
-  copying to. **Default:** `0`
+  copying to. **Default:** `0`.
 * `sourceStart` {integer} The offset within `buf` at which to begin copying from.
-  **Default:** `0`
+  **Default:** `0`.
 * `sourceEnd` {integer} The offset within `buf` at which to stop copying (not
-  inclusive). **Default:** [`buf.length`]
+  inclusive). **Default:** [`buf.length`].
 * Returns: {integer} The number of bytes copied.
 
 Copies data from a region of `buf` to a region in `target` even if the `target`
@@ -1146,10 +1146,10 @@ changes:
 -->
 
 * `value` {string|Buffer|integer} The value to fill `buf` with.
-* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`
-* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`]
+* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`.
+* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`].
 * `encoding` {string} If `value` is a string, this is its encoding.
-  **Default:** `'utf8'`
+  **Default:** `'utf8'`.
 * Returns: {Buffer} A reference to `buf`.
 
 Fills `buf` with the specified `value`. If the `offset` and `end` are not given,
@@ -1197,9 +1197,9 @@ added: v5.3.0
 -->
 
 * `value` {string|Buffer|integer} What to search for.
-* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`
+* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`.
 * `encoding` {string} If `value` is a string, this is its encoding.
-  **Default:** `'utf8'`
+  **Default:** `'utf8'`.
 * Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise.
 
 Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`].
@@ -1237,9 +1237,9 @@ changes:
 -->
 
 * `value` {string|Buffer|Uint8Array|integer} What to search for.
-* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`
+* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`.
 * `encoding` {string} If `value` is a string, this is its encoding.
-  **Default:** `'utf8'`
+  **Default:** `'utf8'`.
 * Returns: {integer} The index of the first occurrence of `value` in `buf` or `-1`
   if `buf` does not contain `value`.
 
@@ -1339,9 +1339,9 @@ changes:
 
 * `value` {string|Buffer|Uint8Array|integer} What to search for.
 * `byteOffset` {integer} Where to begin searching in `buf`.
-  **Default:** [`buf.length`]` - 1`
+  **Default:** [`buf.length`]` - 1`.
 * `encoding` {string} If `value` is a string, this is its encoding.
-  **Default:** `'utf8'`
+  **Default:** `'utf8'`.
 * Returns: {integer} The index of the last occurrence of `value` in `buf` or `-1`
   if `buf` does not contain `value`.
 
@@ -1761,9 +1761,9 @@ changes:
                  calculations with them.
 -->
 
-* `start` {integer} Where the new `Buffer` will start. **Default:** `0`
+* `start` {integer} Where the new `Buffer` will start. **Default:** `0`.
 * `end` {integer} Where the new `Buffer` will end (not inclusive).
-  **Default:** [`buf.length`]
+  **Default:** [`buf.length`].
 * Returns: {Buffer}
 
 Returns a new `Buffer` that references the same memory as the original, but
@@ -1932,10 +1932,10 @@ console.log(copy);
 added: v0.1.90
 -->
 
-* `encoding` {string} The character encoding to decode to. **Default:** `'utf8'`
-* `start` {integer} The byte offset to start decoding at. **Default:** `0`
+* `encoding` {string} The character encoding to decode to. **Default:** `'utf8'`.
+* `start` {integer} The byte offset to start decoding at. **Default:** `0`.
 * `end` {integer} The byte offset to stop decoding at (not inclusive).
-  **Default:** [`buf.length`]
+  **Default:** [`buf.length`].
 * Returns: {string}
 
 Decodes `buf` to a string according to the specified character encoding in
@@ -2009,9 +2009,9 @@ added: v0.1.90
 -->
 
 * `string` {string} String to be written to `buf`.
-* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0`
-* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset`
-* `encoding` {string} The character encoding of `string`. **Default:** `'utf8'`
+* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0`.
+* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset`.
+* `encoding` {string} The character encoding of `string`. **Default:** `'utf8'`.
 * Returns: {integer} Number of bytes written.
 
 Writes `string` to `buf` at `offset` according to the character encoding in `encoding`.
@@ -2326,7 +2326,7 @@ added: v0.5.5
 * `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - byteLength`.
 * `byteLength` {integer} Number of bytes to write. Must satisfy: `0 < byteLength <= 6`.
 * `noAssert` {boolean} Skip `value`, `offset`, and `byteLength` validation?
-  **Default:** `false`
+  **Default:** `false`.
 * Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `byteLength` bytes of `value` to `buf` at the specified `offset`.