doc: remove dashes

The use of dashes -- in general, but especially in our docs -- can be
problematic. It is used inconsistently and there is always another form
of punctuation that is as good or better for the situation. In an effort
to reduce the number of variations we use to display the same types of
information, remove the various uses of dashes from the documentation.

PR-URL: #30101
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Richard Lau <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: James M Snell <[email protected]>

doc/api/addons.md

@@ -11,8 +11,7 @@ provide an interface between JavaScript running in Node.js and C/C++ libraries.
 There are three options for implementing Addons: N-API, nan, or direct
 use of internal V8, libuv and Node.js libraries. Unless you need direct
 access to functionality which is not exposed by N-API, use N-API.
-Refer to the section [C/C++ Addons - N-API](n-api.html)
-for more information on N-API.
+Refer to [C/C++ Addons with N-API](n-api.html) for more information on N-API.
 
 When not using N-API, implementing Addons is complicated,
 involving knowledge of several components and APIs:
@@ -435,8 +434,8 @@ NAPI_MODULE(NODE_GYP_MODULE_NAME, init)
 }  // namespace demo
 ```
 
-The functions available and how to use them are documented in the
-section titled [C/C++ Addons - N-API](n-api.html).
+The functions available and how to use them are documented in
+[C/C++ Addons with N-API](n-api.html).
 
 ## Addon examples
 

doc/api/buffer.md

@@ -182,28 +182,28 @@ console.log(Buffer.from('fhqwhgads', 'utf16le'));
 
 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
+* `'utf8'`: Multibyte encoded Unicode characters. Many web pages and other
   document formats use UTF-8.
 
-* `'utf16le'` - 2 or 4 bytes, little-endian encoded Unicode characters.
+* `'utf16le'`: 2 or 4 bytes, little-endian encoded Unicode characters.
   Surrogate pairs (U+10000 to U+10FFFF) are supported.
 
-* `'ucs2'` - Alias of `'utf16le'`.
+* `'ucs2'`: Alias of `'utf16le'`.
 
-* `'base64'` - Base64 encoding. When creating a `Buffer` from a string,
+* `'base64'`: Base64 encoding. When creating a `Buffer` from a string,
   this encoding will also correctly accept "URL and Filename Safe Alphabet" as
   specified in [RFC 4648, Section 5][].
 
-* `'latin1'` - A way of encoding the `Buffer` into a one-byte encoded string
+* `'latin1'`: A way of encoding the `Buffer` into a one-byte encoded string
   (as defined by the IANA in [RFC 1345][],
   page 63, to be the Latin-1 supplement block and C0/C1 control codes).
 
-* `'binary'` - Alias for `'latin1'`.
+* `'binary'`: Alias for `'latin1'`.
 
-* `'hex'` - Encode each byte as two hexadecimal characters.
+* `'hex'`: Encode each byte as two hexadecimal characters.
 
 Modern Web browsers follow the [WHATWG Encoding Standard][] which aliases
 both `'latin1'` and `'ISO-8859-1'` to `'win-1252'`. This means that while doing
@@ -1003,8 +1003,8 @@ The index operator `[index]` can be used to get and set the octet at position
 range is between `0x00` and `0xFF` (hex) or `0` and `255` (decimal).
 
 This operator is inherited from `Uint8Array`, so its behavior on out-of-bounds
-access is the same as `UInt8Array` - that is, getting returns `undefined` and
-setting does nothing.
+access is the same as `UInt8Array`. In other words, getting returns `undefined`
+and setting does nothing.
 
 ```js
 // Copy an ASCII string into a `Buffer` one byte at a time.

doc/api/child_process.md

@@ -599,21 +599,21 @@ equal to `['pipe', 'pipe', 'pipe']`.
 
 For convenience, `options.stdio` may be one of the following strings:
 
-* `'pipe'` - equivalent to `['pipe', 'pipe', 'pipe']` (the default)
-* `'ignore'` - equivalent to `['ignore', 'ignore', 'ignore']`
-* `'inherit'` - equivalent to `['inherit', 'inherit', 'inherit']` or `[0, 1, 2]`
+* `'pipe'`: equivalent to `['pipe', 'pipe', 'pipe']` (the default)
+* `'ignore'`: equivalent to `['ignore', 'ignore', 'ignore']`
+* `'inherit'`: equivalent to `['inherit', 'inherit', 'inherit']` or `[0, 1, 2]`
 
 Otherwise, the value of `options.stdio` is an array where each index corresponds
 to an fd in the child. The fds 0, 1, and 2 correspond to stdin, stdout,
 and stderr, respectively. Additional fds can be specified to create additional
 pipes between the parent and child. The value is one of the following:
 
-1. `'pipe'` - Create a pipe between the child process and the parent process.
+1. `'pipe'`: Create a pipe between the child process and the parent process.
    The parent end of the pipe is exposed to the parent as a property on the
    `child_process` object as [`subprocess.stdio[fd]`][`subprocess.stdio`]. Pipes
-   created for fds 0 - 2 are also available as [`subprocess.stdin`][],
+   created for fds 0, 1, and 2 are also available as [`subprocess.stdin`][],
    [`subprocess.stdout`][] and [`subprocess.stderr`][], respectively.
-2. `'ipc'` - Create an IPC channel for passing messages/file descriptors
+2. `'ipc'`: Create an IPC channel for passing messages/file descriptors
    between parent and child. A [`ChildProcess`][] may have at most one IPC
    stdio file descriptor. Setting this option enables the
    [`subprocess.send()`][] method. If the child is a Node.js process, the
@@ -624,25 +624,25 @@ pipes between the parent and child. The value is one of the following:
    Accessing the IPC channel fd in any way other than [`process.send()`][]
    or using the IPC channel with a child process that is not a Node.js instance
    is not supported.
-3. `'ignore'` - Instructs Node.js to ignore the fd in the child. While Node.js
-   will always open fds 0 - 2 for the processes it spawns, setting the fd to
-   `'ignore'` will cause Node.js to open `/dev/null` and attach it to the
+3. `'ignore'`: Instructs Node.js to ignore the fd in the child. While Node.js
+   will always open fds 0, 1, and 2 for the processes it spawns, setting the fd
+   to `'ignore'` will cause Node.js to open `/dev/null` and attach it to the
    child's fd.
-4. `'inherit'` - Pass through the corresponding stdio stream to/from the
+4. `'inherit'`: Pass through the corresponding stdio stream to/from the
    parent process. In the first three positions, this is equivalent to
    `process.stdin`, `process.stdout`, and `process.stderr`, respectively. In
    any other position, equivalent to `'ignore'`.
-5. {Stream} object - Share a readable or writable stream that refers to a tty,
+5. {Stream} object: Share a readable or writable stream that refers to a tty,
    file, socket, or a pipe with the child process. The stream's underlying
    file descriptor is duplicated in the child process to the fd that
    corresponds to the index in the `stdio` array. The stream must have an
    underlying descriptor (file streams do not until the `'open'` event has
    occurred).
-6. Positive integer - The integer value is interpreted as a file descriptor
+6. Positive integer: The integer value is interpreted as a file descriptor
    that is currently open in the parent process. It is shared with the child
    process, similar to how {Stream} objects can be shared. Passing sockets
    is not supported on Windows.
-7. `null`, `undefined` - Use default value. For stdio fds 0, 1, and 2 (in other
+7. `null`, `undefined`: Use default value. For stdio fds 0, 1, and 2 (in other
    words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the
    default is `'ignore'`.
 

doc/api/cli.md

@@ -39,7 +39,7 @@ For example, `--pending-deprecation` is equivalent to `--pending_deprecation`.
 added: v8.0.0
 -->
 
-Alias for stdin, analogous to the use of - in other command line utilities,
+Alias for stdin. Analogous to the use of `-` in other command line utilities,
 meaning that the script will be read from stdin, and the rest of the options
 are passed to that script.
 

doc/api/crypto.md

@@ -1417,15 +1417,15 @@ If `privateKey` is not a [`KeyObject`][], this function behaves as if
 `privateKey` had been passed to [`crypto.createPrivateKey()`][]. If it is an
 object, the following additional properties can be passed:
 
-* `padding`: {integer} - Optional padding value for RSA, one of the following:
+* `padding` {integer} Optional padding value for RSA, one of the following:
   * `crypto.constants.RSA_PKCS1_PADDING` (default)
   * `crypto.constants.RSA_PKCS1_PSS_PADDING`
 
   `RSA_PKCS1_PSS_PADDING` will use MGF1 with the same hash function
   used to sign the message as specified in section 3.1 of [RFC 4055][], unless
   an MGF1 hash function has been specified as part of the key in compliance with
   section 3.3 of [RFC 4055][].
-* `saltLength`: {integer} - salt length for when padding is
+* `saltLength` {integer} Salt length for when padding is
   `RSA_PKCS1_PSS_PADDING`. The special value
   `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
   size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the
@@ -1526,15 +1526,15 @@ If `object` is not a [`KeyObject`][], this function behaves as if
 `object` had been passed to [`crypto.createPublicKey()`][]. If it is an
 object, the following additional properties can be passed:
 
-* `padding`: {integer} - Optional padding value for RSA, one of the following:
+* `padding` {integer} Optional padding value for RSA, one of the following:
   * `crypto.constants.RSA_PKCS1_PADDING` (default)
   * `crypto.constants.RSA_PKCS1_PSS_PADDING`
 
   `RSA_PKCS1_PSS_PADDING` will use MGF1 with the same hash function
   used to verify the message as specified in section 3.1 of [RFC 4055][], unless
   an MGF1 hash function has been specified as part of the key in compliance with
   section 3.3 of [RFC 4055][].
-* `saltLength`: {integer} - salt length for when padding is
+* `saltLength` {integer} Salt length for when padding is
   `RSA_PKCS1_PSS_PADDING`. The special value
   `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
   size, `crypto.constants.RSA_PSS_SALTLEN_AUTO` (default) causes it to be
@@ -2891,13 +2891,13 @@ If `key` is not a [`KeyObject`][], this function behaves as if `key` had been
 passed to [`crypto.createPrivateKey()`][]. If it is an object, the following
 additional properties can be passed:
 
-* `padding`: {integer} - Optional padding value for RSA, one of the following:
+* `padding` {integer} Optional padding value for RSA, one of the following:
   * `crypto.constants.RSA_PKCS1_PADDING` (default)
   * `crypto.constants.RSA_PKCS1_PSS_PADDING`
 
   `RSA_PKCS1_PSS_PADDING` will use MGF1 with the same hash function
   used to sign the message as specified in section 3.1 of [RFC 4055][].
-* `saltLength`: {integer} - salt length for when padding is
+* `saltLength` {integer} Salt length for when padding is
   `RSA_PKCS1_PSS_PADDING`. The special value
   `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
   size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the
@@ -2944,13 +2944,13 @@ If `key` is not a [`KeyObject`][], this function behaves as if `key` had been
 passed to [`crypto.createPublicKey()`][]. If it is an object, the following
 additional properties can be passed:
 
-* `padding`: {integer} - Optional padding value for RSA, one of the following:
+* `padding` {integer} Optional padding value for RSA, one of the following:
   * `crypto.constants.RSA_PKCS1_PADDING` (default)
   * `crypto.constants.RSA_PKCS1_PSS_PADDING`
 
   `RSA_PKCS1_PSS_PADDING` will use MGF1 with the same hash function
   used to sign the message as specified in section 3.1 of [RFC 4055][].
-* `saltLength`: {integer} - salt length for when padding is
+* `saltLength` {integer} Salt length for when padding is
   `RSA_PKCS1_PSS_PADDING`. The special value
   `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
   size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the

doc/api/debugger.md

@@ -104,21 +104,21 @@ To begin watching an expression, type `watch('my_expression')`. The command
 
 ### Stepping
 
-* `cont`, `c` - Continue execution
-* `next`, `n` - Step next
-* `step`, `s` - Step in
-* `out`, `o` - Step out
-* `pause` - Pause running code (like pause button in Developer Tools)
+* `cont`, `c`: Continue execution
+* `next`, `n`: Step next
+* `step`, `s`: Step in
+* `out`, `o`: Step out
+* `pause`: Pause running code (like pause button in Developer Tools)
 
 ### Breakpoints
 
-* `setBreakpoint()`, `sb()` - Set breakpoint on current line
-* `setBreakpoint(line)`, `sb(line)` - Set breakpoint on specific line
-* `setBreakpoint('fn()')`, `sb(...)` - Set breakpoint on a first statement in
+* `setBreakpoint()`, `sb()`: Set breakpoint on current line
+* `setBreakpoint(line)`, `sb(line)`: Set breakpoint on specific line
+* `setBreakpoint('fn()')`, `sb(...)`: Set breakpoint on a first statement in
 functions body
-* `setBreakpoint('script.js', 1)`, `sb(...)` - Set breakpoint on first line of
+* `setBreakpoint('script.js', 1)`, `sb(...)`: Set breakpoint on first line of
 `script.js`
-* `clearBreakpoint('script.js', 1)`, `cb(...)` - Clear breakpoint in `script.js`
+* `clearBreakpoint('script.js', 1)`, `cb(...)`: Clear breakpoint in `script.js`
 on line 1
 
 It is also possible to set a breakpoint in a file (module) that
@@ -147,26 +147,26 @@ debug>
 
 ### Information
 
-* `backtrace`, `bt` - Print backtrace of current execution frame
-* `list(5)` - List scripts source code with 5 line context (5 lines before and
+* `backtrace`, `bt`: Print backtrace of current execution frame
+* `list(5)`: List scripts source code with 5 line context (5 lines before and
 after)
-* `watch(expr)` - Add expression to watch list
-* `unwatch(expr)` - Remove expression from watch list
-* `watchers` - List all watchers and their values (automatically listed on each
+* `watch(expr)`: Add expression to watch list
+* `unwatch(expr)`: Remove expression from watch list
+* `watchers`: List all watchers and their values (automatically listed on each
 breakpoint)
-* `repl` - Open debugger's repl for evaluation in debugging script's context
-* `exec expr` - Execute an expression in debugging script's context
+* `repl`: Open debugger's repl for evaluation in debugging script's context
+* `exec expr`: Execute an expression in debugging script's context
 
 ### Execution control
 
-* `run` - Run script (automatically runs on debugger's start)
-* `restart` - Restart script
-* `kill` - Kill script
+* `run`: Run script (automatically runs on debugger's start)
+* `restart`: Restart script
+* `kill`: Kill script
 
 ### Various
 
-* `scripts` - List all loaded scripts
-* `version` - Display V8's version
+* `scripts`: List all loaded scripts
+* `version`: Display V8's version
 
 ## Advanced Usage
 

doc/api/deprecations.md

@@ -141,17 +141,17 @@ API usability issues that can lead to accidental security issues.
 As an alternative, use one of the following methods of constructing `Buffer`
 objects:
 
-* [`Buffer.alloc(size[, fill[, encoding]])`][alloc] - Create a `Buffer` with
+* [`Buffer.alloc(size[, fill[, encoding]])`][alloc]: Create a `Buffer` with
   *initialized* memory.
-* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with
+* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size]: Create a `Buffer` with
   *uninitialized* memory.
-* [`Buffer.allocUnsafeSlow(size)`][] - Create a `Buffer` with *uninitialized*
+* [`Buffer.allocUnsafeSlow(size)`][]: Create a `Buffer` with *uninitialized*
    memory.
-* [`Buffer.from(array)`][] - Create a `Buffer` with a copy of `array`
+* [`Buffer.from(array)`][]: Create a `Buffer` with a copy of `array`
 * [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] -
   Create a `Buffer` that wraps the given `arrayBuffer`.
-* [`Buffer.from(buffer)`][] - Create a `Buffer` that copies `buffer`.
-* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer`
+* [`Buffer.from(buffer)`][]: Create a `Buffer` that copies `buffer`.
+* [`Buffer.from(string[, encoding])`][from_string_encoding]: Create a `Buffer`
   that copies `string`.
 
 Without `--pending-deprecation`, runtime warnings occur only for code not in

doc/api/dgram.md

@@ -706,8 +706,8 @@ changes:
   * `ipv6Only` {boolean} Setting `ipv6Only` to `true` will
     disable dual-stack support, i.e., binding to address `::` won't make
     `0.0.0.0` be bound. **Default:** `false`.
-  * `recvBufferSize` {number} - Sets the `SO_RCVBUF` socket value.
-  * `sendBufferSize` {number} - 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. **Default:** [`dns.lookup()`][].
 * `callback` {Function} Attached as a listener for `'message'` events. Optional.
 * Returns: {dgram.Socket}
@@ -725,8 +725,8 @@ and port can be retrieved using [`socket.address().address`][] and
 added: v0.1.99
 -->
 
-* `type` {string} - Either `'udp4'` or `'udp6'`.
-* `callback` {Function} - Attached as a listener to `'message'` events.
+* `type` {string} Either `'udp4'` or `'udp6'`.
+* `callback` {Function} Attached as a listener to `'message'` events.
 * Returns: {dgram.Socket}
 
 Creates a `dgram.Socket` object of the specified `type`.

doc/api/esm.md

@@ -286,7 +286,7 @@ throw when an attempt is made to import them:
 
 ```js
 import submodule from 'es-module-package/private-module.js';
-// Throws - Module not found
+// Throws ERR_MODULE_NOT_FOUND
 ```
 
 > Note: this is not a strong encapsulation as any private modules can still be