doc: standardize function param/object prop style

PR-URL: https://github.com/nodejs/node/pull/13769
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

doc/STYLE_GUIDE.md

@@ -65,8 +65,16 @@
   * Make the "Note:" label italic, i.e. `*Note*:`.
   * 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][]
+* Function returns should use the following format:
+  * <code>* Returns: {type|type2} Optional description.</code>
+  * E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code>
 
-[plugin]: http://editorconfig.org/#download
-[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
 [Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash
+[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
+[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
 [The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage
+[plugin]: http://editorconfig.org/#download

doc/api/addons.md

@@ -1060,8 +1060,8 @@ has ended but before the JavaScript VM is terminated and Node.js shuts down.
 
 #### void AtExit(callback, args)
 
-* `callback`: `void (*)(void*)` - A pointer to the function to call at exit.
-* `args`: `void*` - A pointer to pass to the callback at exit.
+* `callback` {void (\*)(void\*)} A pointer to the function to call at exit.
+* `args` {void\*} A pointer to pass to the callback at exit.
 
 Registers exit hooks that run after the event loop has ended but before the VM
 is killed.

doc/api/assert.md

@@ -306,9 +306,9 @@ added: v0.1.21
 -->
 * `actual` {any}
 * `expected` {any}
-* `message` {any} (default: 'Failed')
-* `operator` {string} (default: '!=')
-* `stackStartFunction` {function} (default: `assert.fail`)
+* `message` {any} **Default:** `'Failed'`
+* `operator` {string} **Default:** '!='
+* `stackStartFunction` {function} **Default:** `assert.fail`
 
 Throws an `AssertionError`. If `message` is falsy, the error message is set as
 the values of `actual` and `expected` separated by the provided `operator`. If

doc/api/async_hooks.md

@@ -79,12 +79,12 @@ function promiseResolve(asyncId) { }
 added: REPLACEME
 -->
 
-* `callbacks` {Object} the [Hook Callbacks][] to register
+* `callbacks` {Object} The [Hook Callbacks][] to register
   * `init` {Function} The [`init` callback][].
   * `before` {Function} The [`before` callback][].
   * `after` {Function} The [`after` callback][].
   * `destroy` {Function} The [`destroy` callback][].
-* Returns: `{AsyncHook}` instance used for disabling and enabling hooks
+* Returns: `{AsyncHook}` Instance used for disabling and enabling hooks
 
 Registers functions to be called for different lifetime events of each async
 operation.
@@ -168,7 +168,7 @@ doing this the otherwise infinite recursion is broken.
 
 #### `asyncHook.enable()`
 
-* Returns {AsyncHook} A reference to `asyncHook`.
+* Returns: {AsyncHook} A reference to `asyncHook`.
 
 Enable the callbacks for a given `AsyncHook` instance. If no callbacks are
 provided enabling is a noop.
@@ -184,7 +184,7 @@ const hook = async_hooks.createHook(callbacks).enable();
 
 #### `asyncHook.disable()`
 
-* Returns {AsyncHook} A reference to `asyncHook`.
+* Returns: {AsyncHook} A reference to `asyncHook`.
 
 Disable the callbacks for a given `AsyncHook` instance from the global pool of
 AsyncHook callbacks to be executed. Once a hook has been disabled it will not
@@ -200,12 +200,12 @@ instance is destructed.
 
 ##### `init(asyncId, type, triggerAsyncId, resource)`
 
-* `asyncId` {number} a unique ID for the async resource
-* `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 operation,
-  needs to be released during _destroy_
+* `asyncId` {number} A unique ID for the async resource.
+* `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 operation,
+  needs to be released during _destroy_.
 
 Called when a class is constructed that has the _possibility_ to emit an
 asynchronous event. This _does not_ mean the instance must call
@@ -468,7 +468,7 @@ init for PROMISE with id 6, trigger id: 5  # the Promise returned by then()
 
 #### `async_hooks.executionAsyncId()`
 
-* Returns {number} the `asyncId` of the current execution context. Useful to
+* Returns: {number} The `asyncId` of the current execution context. Useful to
   track when something calls.
 
 For example:
@@ -502,7 +502,7 @@ const server = net.createServer(function onConnection(conn) {
 
 #### `async_hooks.triggerAsyncId()`
 
-* Returns {number} the ID of the resource responsible for calling the callback
+* Returns: {number} The ID of the resource responsible for calling the callback
   that is currently being executed.
 
 For example:
@@ -569,9 +569,9 @@ asyncResource.triggerAsyncId();
 #### `AsyncResource(type[, triggerAsyncId])`
 
 * arguments
-  * `type` {string} the type of async event
-  * `triggerAsyncId` {number} the ID of the execution context that created this
-    async event
+  * `type` {string} The type of async event.
+  * `triggerAsyncId` {number} The ID of the execution context that created this
+    async event.
 
 Example usage:
 
@@ -599,7 +599,7 @@ class DBQuery extends AsyncResource {
 
 #### `asyncResource.emitBefore()`
 
-* Returns {undefined}
+* Returns: {undefined}
 
 Call all `before` callbacks to notify that a new asynchronous execution context
 is being entered. If nested calls to `emitBefore()` are made, the stack of
@@ -607,7 +607,7 @@ is being entered. If nested calls to `emitBefore()` are made, the stack of
 
 #### `asyncResource.emitAfter()`
 
-* Returns {undefined}
+* Returns: {undefined}
 
 Call all `after` callbacks. If nested calls to `emitBefore()` were made, then
 make sure the stack is unwound properly. Otherwise an error will be thrown.
@@ -618,7 +618,7 @@ called for all `asyncId`s on the stack if the error is handled by a domain or
 
 #### `asyncResource.emitDestroy()`
 
-* Returns {undefined}
+* Returns: {undefined}
 
 Call all `destroy` hooks. This should only ever be called once. An error will
 be thrown if it is called more than once. This **must** be manually called. If
@@ -627,11 +627,11 @@ never be called.
 
 #### `asyncResource.asyncId()`
 
-* Returns {number} the unique `asyncId` assigned to the resource.
+* Returns: {number} The unique `asyncId` assigned to the resource.
 
 #### `asyncResource.triggerAsyncId()`
 
-* Returns {number} the same `triggerAsyncId` that is passed to the `AsyncResource`
+* Returns: {number} The same `triggerAsyncId` that is passed to the `AsyncResource`
 constructor.
 
 [`after` callback]: #async_hooks_after_asyncid

doc/api/buffer.md

@@ -172,7 +172,7 @@ console.log(buf.toString('base64'));
 
 The character encodings currently supported by Node.js include:
 
-* `'ascii'` - for 7-bit ASCII data only. This encoding is fast and will strip
+* `'ascii'` - For 7-bit ASCII data only. This encoding is fast and will strip
   the high bit if set.
 
 * `'utf8'` - Multibyte encoded Unicode characters. Many web pages and other
@@ -330,7 +330,7 @@ changes:
 
 > Stability: 0 - Deprecated: Use [`Buffer.from(array)`] instead.
 
-* `array` {Array} An array of bytes to copy from
+* `array` {integer[]} An array of bytes to copy from.
 
 Allocates a new `Buffer` using an `array` of octets.
 
@@ -410,7 +410,7 @@ changes:
 
 > Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead.
 
-* `buffer` {Buffer} An existing `Buffer` to copy data from
+* `buffer` {Buffer} An existing `Buffer` to copy data from.
 
 Copies the passed `buffer` data onto a new `Buffer` instance.
 
@@ -447,7 +447,7 @@ changes:
 > Stability: 0 - Deprecated: Use [`Buffer.alloc()`] instead (also see
 > [`Buffer.allocUnsafe()`]).
 
-* `size` {integer} The desired length of the new `Buffer`
+* `size` {integer} The desired length of the new `Buffer`.
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
 [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
@@ -483,7 +483,7 @@ changes:
 > Stability: 0 - Deprecated:
 > Use [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] instead.
 
-* `string` {string} String to encode
+* `string` {string} String to encode.
 * `encoding` {string} The encoding of `string`. **Default:** `'utf8'`
 
 Creates a new `Buffer` containing the given JavaScript string `string`. If
@@ -512,7 +512,7 @@ console.log(buf2.toString());
 added: v5.10.0
 -->
 
-* `size` {integer} The desired length of the new `Buffer`
+* `size` {integer} The desired length of the new `Buffer`.
 * `fill` {string|Buffer|integer} A value to pre-fill the new `Buffer` with.
   **Default:** `0`
 * `encoding` {string} If `fill` is a string, this is its encoding.
@@ -573,7 +573,7 @@ changes:
     description: Passing a negative `size` will now throw an error.
 -->
 
-* `size` {integer} The desired length of the new `Buffer`
+* `size` {integer} The desired length of the new `Buffer`.
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
 [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
@@ -619,7 +619,7 @@ additional performance that [`Buffer.allocUnsafe()`] provides.
 added: v5.12.0
 -->
 
-* `size` {integer} The desired length of the new `Buffer`
+* `size` {integer} The desired length of the new `Buffer`.
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
 [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
@@ -680,10 +680,10 @@ changes:
 -->
 
 * `string` {string|Buffer|TypedArray|DataView|ArrayBuffer} A value to
-  calculate the length of
+  calculate the length of.
 * `encoding` {string} If `string` is a string, this is its encoding.
   **Default:** `'utf8'`
-* Returns: {integer} The number of bytes contained within `string`
+* Returns: {integer} The number of bytes contained within `string`.
 
 Returns the actual byte length of a string. This is not the same as
 [`String.prototype.length`] since that returns the number of *characters* in
@@ -744,9 +744,9 @@ changes:
     description: The elements of `list` can now be `Uint8Array`s.
 -->
 
-* `list` {Array} List of `Buffer` or [`Uint8Array`] instances to concat
+* `list` {Array} List of `Buffer` or [`Uint8Array`] instances to concat.
 * `totalLength` {integer} Total length of the `Buffer` instances in `list`
-  when concatenated
+  when concatenated.
 * Returns: {Buffer}
 
 Returns a new `Buffer` which is the result of concatenating all the `Buffer`
@@ -859,7 +859,7 @@ A `TypeError` will be thrown if `arrayBuffer` is not an [`ArrayBuffer`].
 added: v5.10.0
 -->
 
-* `buffer` {Buffer} An existing `Buffer` to copy data from
+* `buffer` {Buffer} An existing `Buffer` to copy data from.
 
 Copies the passed `buffer` data onto a new `Buffer` instance.
 
@@ -964,7 +964,7 @@ Returns `true` if `obj` is a `Buffer`, `false` otherwise.
 added: v0.9.1
 -->
 
-* `encoding` {string} A character encoding name to check
+* `encoding` {string} A character encoding name to check.
 * Returns: {boolean}
 
 Returns `true` if `encoding` contains a supported character encoding, or `false`
@@ -1033,7 +1033,7 @@ changes:
     description: Additional parameters for specifying offsets are supported now.
 -->
 
-* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to compare to
+* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to compare to.
 * `targetStart` {integer} The offset within `target` at which to begin
   comparison. **Default:** `0`
 * `targetEnd` {integer} The offset with `target` at which to end comparison
@@ -1192,7 +1192,7 @@ changes:
     description: The arguments can now be `Uint8Array`s.
 -->
 
-* `otherBuffer` {Buffer} A `Buffer` or [`Uint8Array`] to compare to
+* `otherBuffer` {Buffer} A `Buffer` or [`Uint8Array`] to compare to.
 * Returns: {boolean}
 
 Returns `true` if both `buf` and `otherBuffer` have exactly the same bytes,
@@ -1221,12 +1221,12 @@ changes:
     description: The `encoding` parameter is supported now.
 -->
 
-* `value` {string|Buffer|integer} The value to fill `buf` with
-* `offset` {integer} Where to start filling `buf`. **Default:** `0`
+* `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`]
 * `encoding` {string} If `value` is a string, this is its encoding.
   **Default:** `'utf8'`
-* Returns: {Buffer} A reference to `buf`
+* Returns: {Buffer} A reference to `buf`.
 
 Fills `buf` with the specified `value`. If the `offset` and `end` are not given,
 the entire `buf` will be filled. This is meant to be a small simplification to
@@ -1258,11 +1258,11 @@ console.log(Buffer.allocUnsafe(3).fill('\u0222'));
 added: v5.3.0
 -->
 
-* `value` {string|Buffer|integer} What to search for
+* `value` {string|Buffer|integer} What to search for.
 * `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`
 * `encoding` {string} If `value` is a string, this is its encoding.
   **Default:** `'utf8'`
-* Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise
+* Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise.
 
 Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`].
 
@@ -1307,12 +1307,12 @@ changes:
                  is no longer required.
 -->
 
-* `value` {string|Buffer|Uint8Array|integer} What to search for
+* `value` {string|Buffer|Uint8Array|integer} What to search for.
 * `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`
 * `encoding` {string} If `value` is a string, this is its encoding.
   **Default:** `'utf8'`
 * Returns: {integer} The index of the first occurrence of `value` in `buf` or `-1`
-  if `buf` does not contain `value`
+  if `buf` does not contain `value`.
 
 If `value` is:
 
@@ -1420,13 +1420,13 @@ changes:
     description: The `value` can now be a `Uint8Array`.
 -->
 
-* `value` {string|Buffer|Uint8Array|integer} What to search for
+* `value` {string|Buffer|Uint8Array|integer} What to search for.
 * `byteOffset` {integer} Where to begin searching in `buf`.
   **Default:** [`buf.length`]` - 1`
 * `encoding` {string} If `value` is a string, this is its encoding.
   **Default:** `'utf8'`
 * Returns: {integer} The index of the last occurrence of `value` in `buf` or `-1`
-  if `buf` does not contain `value`
+  if `buf` does not contain `value`.
 
 Identical to [`buf.indexOf()`], except `buf` is searched from back to front
 instead of front to back.
@@ -1557,7 +1557,7 @@ The `buf.parent` property is a deprecated alias for `buf.buffer`.
 added: v0.11.15
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 8`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 8`.
 * `noAssert` {boolean} Skip `offset` validation? **Default:** `false`
 * Returns: {number}
 
@@ -1593,7 +1593,7 @@ console.log(buf.readDoubleLE(1, true));
 added: v0.11.15
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 4`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 4`.
 * `noAssert` {boolean} Skip `offset` validation? **Default:** `false`
 * Returns: {number}
 
@@ -1628,7 +1628,7 @@ console.log(buf.readFloatLE(1, true));
 added: v0.5.0
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 1`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 1`.
 * `noAssert` {boolean} Skip `offset` validation? **Default:** `false`
 * Returns: {integer}
 
@@ -1660,7 +1660,7 @@ console.log(buf.readInt8(2));
 added: v0.5.5
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 2`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 2`.
 * `noAssert` {boolean} Skip `offset` validation? **Default:** `false`
 * Returns: {integer}
 
@@ -1694,7 +1694,7 @@ console.log(buf.readInt16LE(1));
 added: v0.5.5
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 4`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 4`.
 * `noAssert` {boolean} Skip `offset` validation? **Default:** `false`
 * Returns: {integer}
 
@@ -1728,9 +1728,9 @@ console.log(buf.readInt32LE(1));
 added: v0.11.15
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - byteLength`
-* `byteLength` {integer} How many bytes to read. Must satisfy: `0 < byteLength <= 6`
-* `noAssert` {boolean} Skip `offset` and `byteLength` validation? **Default:** `false`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - byteLength`.
+* `byteLength` {integer} Number of bytes to read. Must satisfy: `0 < byteLength <= 6`.
+* `noAssert` {boolean} Skip `offset` and `byteLength` validation? **Default:** `false`.
 * Returns: {integer}
 
 Reads `byteLength` number of bytes from `buf` at the specified `offset`
@@ -1760,7 +1760,7 @@ console.log(buf.readIntBE(1, 6).toString(16));
 added: v0.5.0
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 1`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 1`.
 * `noAssert` {boolean} Skip `offset` validation? **Default:** `false`
 * Returns: {integer}
 
@@ -1790,7 +1790,7 @@ console.log(buf.readUInt8(2));
 added: v0.5.5
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 2`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 2`.
 * `noAssert` {boolean} Skip `offset` validation? **Default:** `false`
 * Returns: {integer}
 
@@ -1828,7 +1828,7 @@ console.log(buf.readUInt16LE(2).toString(16));
 added: v0.5.5
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 4`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 4`.
 * `noAssert` {boolean} Skip `offset` validation? **Default:** `false`
 * Returns: {integer}
 
@@ -1860,8 +1860,8 @@ console.log(buf.readUInt32LE(1).toString(16));
 added: v0.11.15
 -->
 
-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - byteLength`
-* `byteLength` {integer} How many bytes to read. Must satisfy: `0 < byteLength <= 6`
+* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - byteLength`.
+* `byteLength` {integer} Number of bytes to read. Must satisfy: `0 < byteLength <= 6`.
 * `noAssert` {boolean} Skip `offset` and `byteLength` validation? **Default:** `false`
 * Returns: {integer}
 
@@ -1963,7 +1963,7 @@ console.log(buf.slice(-5, -2).toString());
 added: v5.10.0
 -->
 
-* Returns: {Buffer} A reference to `buf`
+* Returns: {Buffer} A reference to `buf`.
 
 Interprets `buf` as an array of unsigned 16-bit integers and swaps the byte-order
 *in-place*. Throws a `RangeError` if [`buf.length`] is not a multiple of 2.
@@ -1993,7 +1993,7 @@ buf2.swap16();
 added: v5.10.0
 -->
 
-* Returns: {Buffer} A reference to `buf`
+* Returns: {Buffer} A reference to `buf`.
 
 Interprets `buf` as an array of unsigned 32-bit integers and swaps the byte-order
 *in-place*. Throws a `RangeError` if [`buf.length`] is not a multiple of 4.
@@ -2023,7 +2023,7 @@ buf2.swap32();
 added: v6.3.0
 -->
 
-* Returns: {Buffer} A reference to `buf`
+* Returns: {Buffer} A reference to `buf`.
 
 Interprets `buf` as an array of 64-bit numbers and swaps the byte-order *in-place*.
 Throws a `RangeError` if [`buf.length`] is not a multiple of 8.
@@ -2169,11 +2169,11 @@ for (const value of buf) {
 added: v0.1.90
 -->
 
-* `string` {string} String to be written to `buf`
-* `offset` {integer} Where to start writing `string`. **Default:** `0`
-* `length` {integer} How many bytes to write. **Default:** `buf.length - offset`
+* `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'`
-* Returns: {integer} Number of bytes written
+* Returns: {integer} Number of bytes written.
 
 Writes `string` to `buf` at `offset` according to the character encoding in `encoding`.
 The `length` parameter is the number of bytes to write. If `buf` did not contain
@@ -2197,10 +2197,10 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
 added: v0.11.15
 -->
 
-* `value` {number} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 8`
+* `value` {number} Number to be written to `buf`.
+* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 8`.
 * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `value` to `buf` at the specified `offset` with specified endian
 format (`writeDoubleBE()` writes big endian, `writeDoubleLE()` writes little
@@ -2232,10 +2232,10 @@ console.log(buf);
 added: v0.11.15
 -->
 
-* `value` {number} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 4`
+* `value` {number} Number to be written to `buf`.
+* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 4`.
 * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `value` to `buf` at the specified `offset` with specified endian
 format (`writeFloatBE()` writes big endian, `writeFloatLE()` writes little
@@ -2266,10 +2266,10 @@ console.log(buf);
 added: v0.5.0
 -->
 
-* `value` {integer} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 1`
+* `value` {integer} Number to be written to `buf`.
+* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 1`.
 * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `value` to `buf` at the specified `offset`. `value` *should* be a valid
 signed 8-bit integer. Behavior is undefined when `value` is anything other than
@@ -2298,10 +2298,10 @@ console.log(buf);
 added: v0.5.5
 -->
 
-* `value` {integer} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 2`
+* `value` {integer} Number to be written to `buf`.
+* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 2`.
 * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `value` to `buf` at the specified `offset` with specified endian
 format (`writeInt16BE()` writes big endian, `writeInt16LE()` writes little
@@ -2331,10 +2331,10 @@ console.log(buf);
 added: v0.5.5
 -->
 
-* `value` {integer} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 4`
+* `value` {integer} Number to be written to `buf`.
+* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 4`.
 * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `value` to `buf` at the specified `offset` with specified endian
 format (`writeInt32BE()` writes big endian, `writeInt32LE()` writes little
@@ -2364,12 +2364,12 @@ console.log(buf);
 added: v0.11.15
 -->
 
-* `value` {integer} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - byteLength`
-* `byteLength` {integer} How many bytes to write. Must satisfy: `0 < byteLength <= 6`
+* `value` {integer} Number to be written to `buf`.
+* `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`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `byteLength` bytes of `value` to `buf` at the specified `offset`.
 Supports up to 48 bits of accuracy. Behavior is undefined when `value` is
@@ -2399,10 +2399,10 @@ console.log(buf);
 added: v0.5.0
 -->
 
-* `value` {integer} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 1`
+* `value` {integer} Number to be written to `buf`.
+* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 1`.
 * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `value` to `buf` at the specified `offset`. `value` *should* be a
 valid unsigned 8-bit integer. Behavior is undefined when `value` is anything
@@ -2431,10 +2431,10 @@ console.log(buf);
 added: v0.5.5
 -->
 
-* `value` {integer} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 2`
+* `value` {integer} Number to be written to `buf`.
+* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 2`.
 * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `value` to `buf` at the specified `offset` with specified endian
 format (`writeUInt16BE()` writes big endian, `writeUInt16LE()` writes little
@@ -2468,10 +2468,10 @@ console.log(buf);
 added: v0.5.5
 -->
 
-* `value` {integer} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 4`
+* `value` {integer} Number to be written to `buf`.
+* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 4`.
 * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `value` to `buf` at the specified `offset` with specified endian
 format (`writeUInt32BE()` writes big endian, `writeUInt32LE()` writes little
@@ -2503,12 +2503,12 @@ console.log(buf);
 added: v0.5.5
 -->
 
-* `value` {integer} Number to be written to `buf`
-* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - byteLength`
-* `byteLength` {integer} How many bytes to write. Must satisfy: `0 < byteLength <= 6`
+* `value` {integer} Number to be written to `buf`.
+* `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`
-* Returns: {integer} `offset` plus the number of bytes written
+* Returns: {integer} `offset` plus the number of bytes written.
 
 Writes `byteLength` bytes of `value` to `buf` at the specified `offset`.
 Supports up to 48 bits of accuracy. Behavior is undefined when `value` is
@@ -2552,7 +2552,7 @@ Note that this is a property on the `buffer` module returned by
 added: v3.0.0
 -->
 
-* {integer} The largest size allowed for a single `Buffer` instance
+* {integer} The largest size allowed for a single `Buffer` instance.
 
 An alias for [`buffer.constants.MAX_LENGTH`][]
 
@@ -2568,9 +2568,9 @@ changes:
     description: The `source` parameter can now be a `Uint8Array`.
 -->
 
-* `source` {Buffer|Uint8Array} A `Buffer` or `Uint8Array` instance
-* `fromEnc` {string} The current encoding
-* `toEnc` {string} To target encoding
+* `source` {Buffer|Uint8Array} A `Buffer` or `Uint8Array` instance.
+* `fromEnc` {string} The current encoding.
+* `toEnc` {string} To target encoding.
 
 Re-encodes the given `Buffer` or `Uint8Array` instance from one character
 encoding to another. Returns a new `Buffer` instance.
@@ -2642,7 +2642,7 @@ deprecated: v6.0.0
 
 > Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`] instead.
 
-* `size` {integer} The desired length of the new `SlowBuffer`
+* `size` {integer} The desired length of the new `SlowBuffer`.
 
 Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
 [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be
@@ -2681,7 +2681,7 @@ Note that `buffer.constants` is a property on the `buffer` module returned by
 added: 8.2.0
 -->
 
-* {integer} The largest size allowed for a single `Buffer` instance
+* {integer} The largest size allowed for a single `Buffer` instance.
 
 On 32-bit architectures, this value is `(2^30)-1` (~1GB).
 On 64-bit architectures, this value is `(2^31)-1` (~2GB).
@@ -2693,7 +2693,7 @@ This value is also available as [`buffer.kMaxLength`][].
 added: 8.2.0
 -->
 
-* {integer} The largest length allowed for a single `string` instance
+* {integer} The largest length allowed for a single `string` instance.
 
 Represents the largest `length` that a `string` primitive can have, counted
 in UTF-16 code units.

doc/api/child_process.md

@@ -129,22 +129,23 @@ exec('"my script.cmd" a b', (err, stdout, stderr) => {
 added: v0.1.90
 -->
 
-* `command` {string} The command to run, with space-separated arguments
+* `command` {string} The command to run, with space-separated arguments.
 * `options` {Object}
-  * `cwd` {string} Current working directory of the child process
-  * `env` {Object} Environment key-value pairs
-  * `encoding` {string} (Default: `'utf8'`)
-  * `shell` {string} Shell to execute the command with
-    (Default: `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See
-    [Shell Requirements][] and [Default Windows Shell][].)
   * `timeout` {number} (Default: `0`)
+  * `cwd` {string} Current working directory of the child process.
+  * `env` {Object} Environment key-value pairs.
+  * `encoding` {string} **Default:** `'utf8'`
+  * `shell` {string} Shell to execute the command with.
+    **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See
+    [Shell Requirements][] and [Default Windows Shell][].
+  * `timeout` {number} **Default:** `0`
   * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or
-    stderr. (Default: `200*1024`) If exceeded, the child process is terminated.
+    stderr. **Default:** `200*1024`. If exceeded, the child process is terminated.
     See caveat at [`maxBuffer` and Unicode][].
-  * `killSignal` {string|integer} (Default: `'SIGTERM'`)
-  * `uid` {number} Sets the user identity of the process. (See setuid(2).)
-  * `gid` {number} Sets the group identity of the process. (See setgid(2).)
-* `callback` {Function} called with the output when process terminates
+  * `killSignal` {string|integer} **Default:** `'SIGTERM'`
+  * `uid` {number} Sets the user identity of the process (see setuid(2)).
+  * `gid` {number} Sets the group identity of the process (see setgid(2)).
+* `callback` {Function} called with the output when process terminates.
   * `error` {Error}
   * `stdout` {string|Buffer}
   * `stderr` {string|Buffer}
@@ -239,20 +240,20 @@ lsExample();
 added: v0.1.91
 -->
 
-* `file` {string} The name or path of the executable file to run
-* `args` {Array} List of string arguments
+* `file` {string} The name or path of the executable file to run.
+* `args` {string[]} List of string arguments.
 * `options` {Object}
-  * `cwd` {string} Current working directory of the child process
-  * `env` {Object} Environment key-value pairs
-  * `encoding` {string} (Default: `'utf8'`)
-  * `timeout` {number} (Default: `0`)
+  * `cwd` {string} Current working directory of the child process.
+  * `env` {Object} Environment key-value pairs.
+  * `encoding` {string} **Default:** `'utf8'`
+  * `timeout` {number} **Default:** `0`
   * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or
-    stderr. (Default: `200*1024`) If exceeded, the child process is terminated.
+    stderr. **Default:** `200*1024` If exceeded, the child process is terminated.
     See caveat at [`maxBuffer` and Unicode][].
-  * `killSignal` {string|integer} (Default: `'SIGTERM'`)
-  * `uid` {number} Sets the user identity of the process. (See setuid(2).)
-  * `gid` {number} Sets the group identity of the process. (See setgid(2).)
-* `callback` {Function} called with the output when process terminates
+  * `killSignal` {string|integer} **Default:** `'SIGTERM'`
+  * `uid` {number} Sets the user identity of the process (see setuid(2)).
+  * `gid` {number} Sets the group identity of the process (see setgid(2)).
+* `callback` {Function} Called with the output when process terminates.
   * `error` {Error}
   * `stdout` {string|Buffer}
   * `stderr` {string|Buffer}
@@ -310,24 +311,24 @@ changes:
     description: The `stdio` option is supported now.
 -->
 
-* `modulePath` {string} The module to run in the child
-* `args` {Array} List of string arguments
+* `modulePath` {string} The module to run in the child.
+* `args` {Array} List of string arguments.
 * `options` {Object}
-  * `cwd` {string} Current working directory of the child process
-  * `env` {Object} Environment key-value pairs
-  * `execPath` {string} Executable used to create the child process
-  * `execArgv` {Array} List of string arguments passed to the executable
-    (Default: `process.execArgv`)
+  * `cwd` {string} Current working directory of the child process.
+  * `env` {Object} Environment key-value pairs.
+  * `execPath` {string} Executable used to create the child process.
+  * `execArgv` {Array} List of string arguments passed to the executable.
+    **Default:** `process.execArgv`
   * `silent` {boolean} If `true`, stdin, stdout, and stderr of the child will be
     piped to the parent, otherwise they will be inherited from the parent, see
     the `'pipe'` and `'inherit'` options for [`child_process.spawn()`][]'s
-    [`stdio`][] for more details (Default: `false`)
+    [`stdio`][] for more details. **Default:** `false`
   * `stdio` {Array|string} See [`child_process.spawn()`][]'s [`stdio`][].
     When this option is provided, it overrides `silent`. If the array variant
     is used, it must contain exactly one item with value `'ipc'` or an error
     will be thrown. For instance `[0, 1, 2, 'ipc']`.
-  * `uid` {number} Sets the user identity of the process. (See setuid(2).)
-  * `gid` {number} Sets the group identity of the process. (See setgid(2).)
+  * `uid` {number} Sets the user identity of the process (see setuid(2)).
+  * `gid` {number} Sets the group identity of the process (see setgid(2)).
 * Returns: {ChildProcess}
 
 The `child_process.fork()` method is a special case of
@@ -371,24 +372,24 @@ changes:
     description: The `shell` option is supported now.
 -->
 
-* `command` {string} The command to run
-* `args` {Array} List of string arguments
+* `command` {string} The command to run.
+* `args` {Array} List of string arguments.
 * `options` {Object}
-  * `cwd` {string} Current working directory of the child process
-  * `env` {Object} Environment key-value pairs
+  * `cwd` {string} Current working directory of the child process.
+  * `env` {Object} Environment key-value pairs.
   * `argv0` {string} Explicitly set the value of `argv[0]` sent to the child
     process. This will be set to `command` if not specified.
-  * `stdio` {Array|string} Child's stdio configuration. (See
-    [`options.stdio`][`stdio`])
+  * `stdio` {Array|string} Child's stdio configuration (see
+    [`options.stdio`][`stdio`]).
   * `detached` {boolean} Prepare child to run independently of its parent
     process. Specific behavior depends on the platform, see
-    [`options.detached`][])
-  * `uid` {number} Sets the user identity of the process. (See setuid(2).)
-  * `gid` {number} Sets the group identity of the process. (See setgid(2).)
+    [`options.detached`][]).
+  * `uid` {number} Sets the user identity of the process (see setuid(2)).
+  * `gid` {number} Sets the group identity of the process (see setgid(2)).
   * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses
     `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different
     shell can be specified as a string. See [Shell Requirements][] and
-    [Default Windows Shell][]. Defaults to `false` (no shell).
+    [Default Windows Shell][]. **Default:** `false` (no shell).
 * Returns: {ChildProcess}
 
 The `child_process.spawn()` method spawns a new process using the given
@@ -656,28 +657,28 @@ changes:
     description: The `encoding` option can now explicitly be set to `buffer`.
 -->
 
-* `file` {string} The name or path of the executable file to run
-* `args` {Array} List of string arguments
+* `file` {string} The name or path of the executable file to run.
+* `args` {string[]} List of string arguments.
 * `options` {Object}
-  * `cwd` {string} Current working directory of the child process
+  * `cwd` {string} Current working directory of the child process.
   * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin
-    to the spawned process
+    to the spawned process.
     - supplying this value will override `stdio[0]`
-  * `stdio` {string|Array} Child's stdio configuration. (Default: `'pipe'`)
+  * `stdio` {string|Array} Child's stdio configuration. **Default:** `'pipe'`
     - `stderr` by default will be output to the parent process' stderr unless
       `stdio` is specified
-  * `env` {Object} Environment key-value pairs
-  * `uid` {number} Sets the user identity of the process. (See setuid(2).)
-  * `gid` {number} Sets the group identity of the process. (See setgid(2).)
+  * `env` {Object} Environment key-value pairs.
+  * `uid` {number} Sets the user identity of the process (see setuid(2)).
+  * `gid` {number} Sets the group identity of the process (see setgid(2)).
   * `timeout` {number} In milliseconds the maximum amount of time the process
-    is allowed to run. (Default: `undefined`)
+    is allowed to run. **Default:** `undefined`
   * `killSignal` {string|integer} The signal value to be used when the spawned
-    process will be killed. (Default: `'SIGTERM'`)
+    process will be killed. **Default:** `'SIGTERM'`
   * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or
-    stderr. (Default: `200*1024`) If exceeded, the child process is terminated.
+    stderr. **Default:** `200*1024` If exceeded, the child process is terminated.
     See caveat at [`maxBuffer` and Unicode][].
-  * `encoding` {string} The encoding used for all stdio inputs and outputs. (Default: `'buffer'`)
-* Returns: {Buffer|string} The stdout from the command
+  * `encoding` {string} The encoding used for all stdio inputs and outputs. **Default:** `'buffer'`
+* Returns: {Buffer|string} The stdout from the command.
 
 The `child_process.execFileSync()` method is generally identical to
 [`child_process.execFile()`][] with the exception that the method will not return
@@ -702,31 +703,31 @@ changes:
     description: The `input` option can now be a `Uint8Array`.
 -->
 
-* `command` {string} The command to run
+* `command` {string} The command to run.
 * `options` {Object}
-  * `cwd` {string} Current working directory of the child process
+  * `cwd` {string} Current working directory of the child process.
   * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin
-    to the spawned process
-    - supplying this value will override `stdio[0]`
-  * `stdio` {string|Array} Child's stdio configuration. (Default: `'pipe'`)
+    to the spawned process.
+    - supplying this value will override `stdio[0]`.
+  * `stdio` {string|Array} Child's stdio configuration. **Default:** `'pipe'`
     - `stderr` by default will be output to the parent process' stderr unless
       `stdio` is specified
-  * `env` {Object} Environment key-value pairs
-  * `shell` {string} Shell to execute the command with
-    (Default: `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See
-    [Shell Requirements][] and [Default Windows Shell][].)
-  * `uid` {number} Sets the user identity of the process. (See setuid(2).)
-  * `gid` {number} Sets the group identity of the process. (See setgid(2).)
+  * `env` {Object} Environment key-value pairs.
+  * `shell` {string} Shell to execute the command with.
+    **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See
+    [Shell Requirements][] and [Default Windows Shell][].
+  * `uid` {number} Sets the user identity of the process. (See setuid(2)).
+  * `gid` {number} Sets the group identity of the process. (See setgid(2)).
   * `timeout` {number} In milliseconds the maximum amount of time the process
-    is allowed to run. (Default: `undefined`)
+    is allowed to run. **Default:** `undefined`
   * `killSignal` {string|integer} The signal value to be used when the spawned
-    process will be killed. (Default: `'SIGTERM'`)
+    process will be killed. **Default:** `'SIGTERM'`
   * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or
-    stderr. (Default: `200*1024`) If exceeded, the child process is terminated.
+    stderr. **Default:** `200*1024` If exceeded, the child process is terminated.
     See caveat at [`maxBuffer` and Unicode][].
   * `encoding` {string} The encoding used for all stdio inputs and outputs.
-    (Default: `'buffer'`)
-* Returns: {Buffer|string} The stdout from the command
+    **Default:** `'buffer'`
+* Returns: {Buffer|string} The stdout from the command.
 
 The `child_process.execSync()` method is generally identical to
 [`child_process.exec()`][] with the exception that the method will not return until
@@ -759,38 +760,38 @@ changes:
     description: The `shell` option is supported now.
 -->
 
-* `command` {string} The command to run
-* `args` {Array} List of string arguments
+* `command` {string} The command to run.
+* `args` {Array} List of string arguments.
 * `options` {Object}
-  * `cwd` {string} Current working directory of the child process
+  * `cwd` {string} Current working directory of the child process.
   * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin
-    to the spawned process
-    - supplying this value will override `stdio[0]`
+    to the spawned process.
+    - supplying this value will override `stdio[0]`.
   * `stdio` {string|Array} Child's stdio configuration.
-  * `env` {Object} Environment key-value pairs
-  * `uid` {number} Sets the user identity of the process. (See setuid(2).)
-  * `gid` {number} Sets the group identity of the process. (See setgid(2).)
+  * `env` {Object} Environment key-value pairs.
+  * `uid` {number} Sets the user identity of the process (see setuid(2)).
+  * `gid` {number} Sets the group identity of the process (see setgid(2)).
   * `timeout` {number} In milliseconds the maximum amount of time the process
-    is allowed to run. (Default: `undefined`)
+    is allowed to run. **Default:** `undefined`
   * `killSignal` {string|integer} The signal value to be used when the spawned
-    process will be killed. (Default: `'SIGTERM'`)
+    process will be killed. **Default:** `'SIGTERM'`
   * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or
-    stderr. (Default: `200*1024`) If exceeded, the child process is terminated.
+    stderr. **Default:** `200*1024` If exceeded, the child process is terminated.
     See caveat at [`maxBuffer` and Unicode][].
   * `encoding` {string} The encoding used for all stdio inputs and outputs.
-    (Default: `'buffer'`)
+    **Default:** `'buffer'`
   * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses
     `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different
     shell can be specified as a string. See [Shell Requirements][] and
-    [Default Windows Shell][]. Defaults to `false` (no shell).
+    [Default Windows Shell][]. **Default:** `false` (no shell).
 * Returns: {Object}
-  * `pid` {number} Pid of the child process
-  * `output` {Array} Array of results from stdio output
-  * `stdout` {Buffer|string} The contents of `output[1]`
-  * `stderr` {Buffer|string} The contents of `output[2]`
-  * `status` {number} The exit code of the child process
-  * `signal` {string} The signal used to kill the child process
-  * `error` {Error} The error object if the child process failed or timed out
+  * `pid` {number} Pid of the child process.
+  * `output` {Array} Array of results from stdio output.
+  * `stdout` {Buffer|string} The contents of `output[1]`.
+  * `stderr` {Buffer|string} The contents of `output[2]`.
+  * `status` {number} The exit code of the child process.
+  * `signal` {string} The signal used to kill the child process.
+  * `error` {Error} The error object if the child process failed or timed out.
 
 The `child_process.spawnSync()` method is generally identical to
 [`child_process.spawn()`][] with the exception that the function will not return
@@ -822,8 +823,8 @@ instances of `ChildProcess`.
 added: v0.7.7
 -->
 
-* `code` {number} the exit code if the child exited on its own.
-* `signal` {string} the signal by which the child process was terminated.
+* `code` {number} The exit code if the child exited on its own.
+* `signal` {string} The signal by which the child process was terminated.
 
 The `'close'` event is emitted when the stdio streams of a child process have
 been closed. This is distinct from the [`'exit'`][] event, since multiple
@@ -842,7 +843,7 @@ property is `false`.
 
 ### Event: 'error'
 
-* `err` {Error} the error.
+* `err` {Error} The error.
 
 The `'error'` event is emitted whenever:
 
@@ -861,8 +862,8 @@ See also [`subprocess.kill()`][] and [`subprocess.send()`][].
 added: v0.1.90
 -->
 
-* `code` {number} the exit code if the child exited on its own.
-* `signal` {string} the signal by which the child process was terminated.
+* `code` {number} The exit code if the child exited on its own.
+* `signal` {string} The signal by which the child process was terminated.
 
 The `'exit'` event is emitted after the child process ends. If the process
 exited, `code` is the final exit code of the process, otherwise `null`. If the
@@ -884,8 +885,8 @@ See waitpid(2).
 added: v0.5.9
 -->
 
-* `message` {Object} a parsed JSON object or primitive value.
-* `sendHandle` {Handle} a [`net.Socket`][] or [`net.Server`][] object, or
+* `message` {Object} A parsed JSON object or primitive value.
+* `sendHandle` {Handle} A [`net.Socket`][] or [`net.Server`][] object, or
   undefined.
 
 The `'message'` event is triggered when a child process uses [`process.send()`][]
@@ -910,7 +911,7 @@ no IPC channel currently exists, this property is `undefined`.
 added: v0.7.2
 -->
 
-* {boolean} Set to `false` after `subprocess.disconnect()` is called
+* {boolean} Set to `false` after `subprocess.disconnect()` is called.
 
 The `subprocess.connected` property indicates whether it is still possible to
 send and receive messages from a child process. When `subprocess.connected` is

doc/api/cluster.md

@@ -147,8 +147,8 @@ Within a worker, `process.on('error')` may also be used.
 added: v0.11.2
 -->
 
-* `code` {number} the exit code, if it exited normally.
-* `signal` {string} the name of the signal (e.g. `'SIGHUP'`) that caused
+* `code` {number} The exit code, if it exited normally.
+* `signal` {string} The name of the signal (e.g. `'SIGHUP'`) that caused
   the process to be killed.
 
 Similar to the `cluster.on('exit')` event, but specific to this worker.
@@ -429,7 +429,7 @@ changes:
 * `message` {Object}
 * `sendHandle` {Handle}
 * `callback` {Function}
-* Returns: Boolean
+* Returns: {boolean}
 
 Send a message to a worker or master, optionally with a handle.
 
@@ -480,8 +480,8 @@ added: v0.7.9
 -->
 
 * `worker` {cluster.Worker}
-* `code` {number} the exit code, if it exited normally.
-* `signal` {string} the name of the signal (e.g. `'SIGHUP'`) that caused
+* `code` {number} The exit code, if it exited normally.
+* `signal` {string} The name of the signal (e.g. `'SIGHUP'`) that caused
   the process to be killed.
 
 When any of the workers die the cluster module will emit the `'exit'` event.
@@ -630,8 +630,8 @@ If accuracy is important, use `cluster.settings`.
 added: v0.7.7
 -->
 
-* `callback` {Function} called when all workers are disconnected and handles are
-  closed
+* `callback` {Function} Called when all workers are disconnected and handles are
+  closed.
 
 Calls `.disconnect()` on each worker in `cluster.workers`.
 
@@ -648,7 +648,7 @@ added: v0.6.0
 -->
 
 * `env` {Object} Key/value pairs to add to worker process environment.
-* return {cluster.Worker}
+* Returns: {cluster.Worker}
 
 Spawn a new worker process.
 
@@ -709,9 +709,9 @@ changes:
     executable. (Default=`process.execArgv`)
   * `exec` {string} File path to worker file.  (Default=`process.argv[1]`)
   * `args` {Array} String arguments passed to worker.
-    (Default=`process.argv.slice(2)`)
+    **Default:** `process.argv.slice(2)`
   * `silent` {boolean} Whether or not to send output to parent's stdio.
-    (Default=`false`)
+    **Default:** `false`
   * `stdio` {Array} Configures the stdio of forked processes. Because the
     cluster module relies on IPC to function, this configuration must contain an
     `'ipc'` entry. When this option is provided, it overrides `silent`.

doc/api/dgram.md

@@ -74,12 +74,12 @@ 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
-  * `family` {string} The address family (`'IPv4'` or `'IPv6'`)
-  * `port` {number} The sender port
-  * `size` {number} The message size
+* `msg` {Buffer} The message.
+* `rinfo` {Object} Remote address information.
+  * `address` {string} The sender address.
+  * `family` {string} The address family (`'IPv4'` or `'IPv6'`).
+  * `port` {number} The sender port.
+  * `size` {number} The message size.
 
 ### socket.addMembership(multicastAddress[, multicastInterface])
 <!-- YAML
@@ -87,7 +87,7 @@ added: v0.6.9
 -->
 
 * `multicastAddress` {string}
-* `multicastInterface` {string}, Optional
+* `multicastInterface` {string}
 
 Tells the kernel to join a multicast group at the given `multicastAddress` and
 `multicastInterface` using the `IP_ADD_MEMBERSHIP` socket option. If the
@@ -109,10 +109,9 @@ properties.
 added: v0.1.99
 -->
 
-* `port` {number} - Integer, Optional
-* `address` {string}, Optional
-* `callback` {Function} with no parameters, Optional. Called when
-  binding is complete.
+* `port` {number} Integer.
+* `address` {string}
+* `callback` {Function} with no parameters. Called when binding is complete.
 
 For UDP sockets, causes the `dgram.Socket` to listen for datagram
 messages on a named `port` and optional `address`. If `port` is not
@@ -161,11 +160,11 @@ server.bind(41234);
 added: v0.11.14
 -->
 
-* `options` {Object} - Required. Supports the following properties:
-  * `port` {number} - Optional.
-  * `address` {string} - Optional.
-  * `exclusive` {boolean} - Optional.
-* `callback` {Function} - Optional.
+* `options` {Object} Required. Supports the following properties:
+  * `port` {Integer}
+  * `address` {string}
+  * `exclusive` {boolean}
+* `callback` {Function}
 
 For UDP sockets, causes the `dgram.Socket` to listen for datagram
 messages on a named `port` and optional `address` that are passed as
@@ -217,7 +216,7 @@ added: v0.6.9
 -->
 
 * `multicastAddress` {string}
-* `multicastInterface` {string}, Optional
+* `multicastInterface` {string}
 
 Instructs the kernel to leave a multicast group at `multicastAddress` using the
 `IP_DROP_MEMBERSHIP` socket option. This method is automatically called by the
@@ -277,12 +276,12 @@ changes:
                  and `length` parameters are optional now.
 -->
 
-* `msg` {Buffer|Uint8Array|string|array} Message to be sent
-* `offset` {number} Integer. Optional. Offset in the buffer where the message starts.
-* `length` {number} Integer. Optional. Number of bytes in the message.
+* `msg` {Buffer|Uint8Array|string|Array} Message to be sent.
+* `offset` {number} Integer. Offset in the buffer where the message starts.
+* `length` {number} Integer. Number of bytes in the message.
 * `port` {number} Integer. Destination port.
-* `address` {string} Destination hostname or IP address. Optional.
-* `callback` {Function} Called when the message has been sent. Optional.
+* `address` {string} Destination hostname or IP address.
+* `callback` {Function} Called when the message has been sent.
 
 Broadcasts a datagram on the socket. The destination `port` and `address` must
 be specified.
@@ -479,7 +478,7 @@ multicast packets will also be received on the local interface.
 added: v0.3.8
 -->
 
-* `ttl` {number} Integer
+* `ttl` {number} Integer.
 
 Sets the `IP_MULTICAST_TTL` socket option.  While TTL generally stands for
 "Time to Live", in this context it specifies the number of IP hops that a
@@ -515,7 +514,7 @@ in bytes.
 added: v0.1.101
 -->
 
-* `ttl` {number} Integer
+* `ttl` {number} Integer.
 
 Sets the `IP_TTL` socket option. While TTL generally stands for "Time to Live",
 in this context it specifies the number of IP hops that a packet is allowed to
@@ -583,12 +582,11 @@ changes:
   * `type` {string} The family of socket. Must be either `'udp4'` or `'udp6'`.
     Required.
   * `reuseAddr` {boolean} When `true` [`socket.bind()`][] will reuse the
-    address, even if another process has already bound a socket on it. Optional.
+    address, even if another process has already bound a socket on it.
     Defaults to `false`.
-  * `recvBufferSize` {number} - Optional. Sets the `SO_RCVBUF` socket value.
-  * `sendBufferSize` {number} - Optional. Sets the `SO_SNDBUF` socket value.
+  * `recvBufferSize` {number} - Sets the `SO_RCVBUF` socket value.
+  * `sendBufferSize` {number} - Sets the `SO_SNDBUF` socket value.
   * `lookup` {Function} Custom lookup function. Defaults to [`dns.lookup()`][].
-    Optional.
 * `callback` {Function} Attached as a listener for `'message'` events. Optional.
 * Returns: {dgram.Socket}
 
@@ -605,9 +603,8 @@ and port can be retrieved using [`socket.address().address`][] and
 added: v0.1.99
 -->
 
-* `type` {string} - Either 'udp4' or 'udp6'
+* `type` {string} - Either 'udp4' or 'udp6'.
 * `callback` {Function} - Attached as a listener to `'message'` events.
-  Optional
 * Returns: {dgram.Socket}
 
 Creates a `dgram.Socket` object of the specified `type`. The `type` argument

doc/api/net.md

@@ -164,7 +164,7 @@ connections use asynchronous [`server.getConnections()`][] instead.
 added: v0.9.7
 -->
 
-* Returns {net.Server}
+* Returns: {net.Server}
 
 Asynchronously get the number of concurrent connections on the server. Works
 when sockets were sent to forks.

doc/api/stream.md

@@ -1624,7 +1624,7 @@ changes:
   any JavaScript value.
 * `encoding` {string} Encoding of string chunks.  Must be a valid
   Buffer encoding, such as `'utf8'` or `'ascii'`
-* Returns {boolean} `true` if additional chunks of data may continued to be
+* Returns: {boolean} `true` if additional chunks of data may continued to be
   pushed; `false` otherwise.
 
 When `chunk` is a `Buffer`, `Uint8Array` or `string`, the `chunk` of data will