doc: fix various nits

* Replace 2 hyphens (--) by spaced m-dashes (—) as per STYLE_GUIDE.md.
* Space infix operators.
* Unify quotes in inline code spans (use only single quotes).
* Unify `* Returns:` (eliminate deviations).
* Dedupe spaces.

Backport-PR-URL: #19761
PR-URL: #19743
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

doc/api/addons.md

@@ -101,7 +101,7 @@ Addon module name is `addon`.
 Once the source code has been written, it must be compiled into the binary
 `addon.node` file. To do so, create a file called `binding.gyp` in the
 top-level of the project describing the build configuration of your module
-using a JSON-like format. This file is used by [node-gyp][] -- a tool written
+using a JSON-like format. This file is used by [node-gyp][] — a tool written
 specifically to compile Node.js Addons.
 
 ```json

doc/api/buffer.md

@@ -395,7 +395,7 @@ deprecated: v6.0.0
 
 * `size` {integer} The desired length of the new `Buffer`.
 
-Allocates a new `Buffer` of `size` bytes.  The `size` must be less than or equal
+Allocates a new `Buffer` of `size` bytes. The `size` must be less than or equal
 to the value of [`buffer.kMaxLength`]. Otherwise, a [`RangeError`] is thrown.
 A zero-length `Buffer` will be created if `size <= 0`.
 

doc/api/child_process.md

@@ -38,7 +38,7 @@ the event loop until the spawned process either exits or is terminated.
 
 For convenience, the `child_process` module provides a handful of synchronous
 and asynchronous alternatives to [`child_process.spawn()`][] and
-[`child_process.spawnSync()`][].  *Note that each of these alternatives are
+[`child_process.spawnSync()`][]. *Note that each of these alternatives are
 implemented on top of [`child_process.spawn()`][] or [`child_process.spawnSync()`][].*
 
   * [`child_process.exec()`][]: spawns a shell and runs a command within that shell,
@@ -140,7 +140,8 @@ added: v0.1.90
      command line parsing should be compatible with `cmd.exe`.
   * `timeout` {number} **Default:** `0`
   * [`maxBuffer`][] {number} Largest amount of data (in bytes) allowed on
-    stdout or stderr - if exceeded child process is killed. **Default:** `200*1024`
+    stdout or stderr - if exceeded child process is killed.
+    **Default:** `200 * 1024`.
   * `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)).
@@ -170,7 +171,7 @@ exec('cat *.js bad_file | wc -l', (error, stdout, stderr) => {
 ```
 
 If a `callback` function is provided, it is called with the arguments
-`(error, stdout, stderr)`. On success, `error` will be `null`.  On error,
+`(error, stdout, stderr)`. On success, `error` will be `null`. On error,
 `error` will be an instance of [`Error`][]. The `error.code` property will be
 the exit code of the child process while `error.signal` will be set to the
 signal that terminated the process. Any exit code other than `0` is considered
@@ -218,7 +219,7 @@ added: v0.1.91
   * `timeout` {number} **Default:** `0`
   * [`maxBuffer`][] {number} Largest amount of data (in bytes) allowed on
     stdout or stderr - if exceeded child process is killed.
-    **Default:**: `200*1024`
+    **Default:** `200 * 1024`.
   * `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)).
@@ -446,7 +447,7 @@ disabled*.
 On non-Windows platforms, if `options.detached` is set to `true`, the child
 process will be made the leader of a new process group and session. Note that
 child processes may continue running after the parent exits regardless of
-whether they are detached or not.  See setsid(2) for more information.
+whether they are detached or not. See setsid(2) for more information.
 
 By default, the parent will wait for the detached child to exit. To prevent
 the parent from waiting for a given `subprocess`, use the `subprocess.unref()`
@@ -656,12 +657,12 @@ The `child_process.execSync()` method is generally identical to
 [`child_process.exec()`][] with the exception that the method will not return until
 the child process has fully closed. When a timeout has been encountered and
 `killSignal` is sent, the method won't return until the process has completely
-exited. *Note that if  the child process intercepts and handles the `SIGTERM`
+exited. *Note that if the child process intercepts and handles the `SIGTERM`
 signal and doesn't exit, the parent process will wait until the child
 process has exited.*
 
 If the process times out, or has a non-zero exit code, this method ***will***
-throw.  The [`Error`][] object will contain the entire result from
+throw. The [`Error`][] object will contain the entire result from
 [`child_process.spawnSync()`][]
 
 **Note: Never pass unsanitised user input to this function. Any input
@@ -997,7 +998,7 @@ properties:
     Defaults to `false`.
 
 The optional `callback` is a function that is invoked after the message is
-sent but before the child may have received it.  The function is called with a
+sent but before the child may have received it. The function is called with a
 single argument: `null` on success, or an [`Error`][] object on failure.
 
 If no `callback` function is provided and the message cannot be sent, an

doc/api/cli.md

@@ -342,7 +342,7 @@ added: v6.12.0
 -->
 
 `options...` are interpreted as if they had been specified on the command line
-before the actual command line (so they can be overriden).  Node will exit with
+before the actual command line (so they can be overriden). Node will exit with
 an error if an option that is not allowed in the environment is used, such as
 `-p` or a script file.
 
@@ -382,7 +382,7 @@ added: v3.0.0
 
 Path to the file used to store the persistent REPL history. The default path is
 `~/.node_repl_history`, which is overridden by this variable. Setting the value
-to an empty string (`""` or `" "`) disables persistent REPL history.
+to an empty string (`''` or `' '`) disables persistent REPL history.
 
 
 ### `NODE_TTY_UNSAFE_ASYNC=1`

doc/api/cluster.md

@@ -90,26 +90,26 @@ Node.js process and a cluster worker differs:
    idea of what the number 7 file descriptor references.
 2. `server.listen(handle)` Listening on handles explicitly will cause
    the worker to use the supplied handle, rather than talk to the master
-   process.  If the worker already has the handle, then it's presumed
+   process. If the worker already has the handle, then it's presumed
    that you know what you are doing.
 3. `server.listen(0)` Normally, this will cause servers to listen on a
-   random port.  However, in a cluster, each worker will receive the
-   same "random" port each time they do `listen(0)`.  In essence, the
-   port is random the first time, but predictable thereafter.  If you
+   random port. However, in a cluster, each worker will receive the
+   same "random" port each time they do `listen(0)`. In essence, the
+   port is random the first time, but predictable thereafter. If you
    want to listen on a unique port, generate a port number based on the
    cluster worker ID.
 
 There is no routing logic in Node.js, or in your program, and no shared
-state between the workers.  Therefore, it is important to design your
+state between the workers. Therefore, it is important to design your
 program such that it does not rely too heavily on in-memory data objects
 for things like sessions and login.
 
 Because workers are all separate processes, they can be killed or
 re-spawned depending on your program's needs, without affecting other
-workers.  As long as there are some workers still alive, the server will
-continue to accept connections.  If no workers are alive, existing connections
-will be dropped and new connections will be refused.  Node.js does not
-automatically manage the number of workers for you, however.  It is your
+workers. As long as there are some workers still alive, the server will
+continue to accept connections. If no workers are alive, existing connections
+will be dropped and new connections will be refused. Node.js does not
+automatically manage the number of workers for you, however. It is your
 responsibility to manage the worker pool for your application's needs.
 
 Although a primary use case for the `cluster` module is networking, it can
@@ -489,7 +489,7 @@ Emitted after the worker IPC channel has disconnected. This can occur when a
 worker exits gracefully, is killed, or is disconnected manually (such as with
 worker.disconnect()).
 
-There may be a delay between the `'disconnect'` and `'exit'` events.  These events
+There may be a delay between the `'disconnect'` and `'exit'` events. These events
 can be used to detect if the process is stuck in a cleanup or if there are
 long-living connections.
 
@@ -582,7 +582,7 @@ The `addressType` is one of:
 * `4` (TCPv4)
 * `6` (TCPv6)
 * `-1` (unix domain socket)
-* `"udp4"` or `"udp6"` (UDP v4 or v6)
+* `'udp4'` or `'udp6'` (UDP v4 or v6)
 
 ## Event: 'message'
 
@@ -709,7 +709,7 @@ distribute IOCP handles without incurring a large performance hit.
 
 `cluster.schedulingPolicy` can also be set through the
 `NODE_CLUSTER_SCHED_POLICY` environment variable. Valid
-values are `"rr"` and `"none"`.
+values are `'rr'` and `'none'`.
 
 ## cluster.settings
 <!-- YAML

doc/api/console.md

@@ -12,7 +12,7 @@ The module exports two specific components:
 * A `Console` class with methods such as `console.log()`, `console.error()` and
   `console.warn()` that can be used to write to any Node.js stream.
 * A global `console` instance configured to write to [`process.stdout`][] and
-  [`process.stderr`][].  The global `console` can be used without calling
+  [`process.stderr`][]. The global `console` can be used without calling
   `require('console')`.
 
 ***Warning***: The global console object's methods are neither consistently

doc/api/crypto.md

@@ -452,7 +452,7 @@ added: v0.5.0
 -->
 
 Returns the Diffie-Hellman generator in the specified `encoding`, which can
-be `'latin1'`, `'hex'`, or `'base64'`. If  `encoding` is provided a string is
+be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is
 returned; otherwise a [`Buffer`][] is returned.
 
 ### diffieHellman.getPrime([encoding])

doc/api/debugger.md

@@ -68,7 +68,7 @@ debug> repl
 Press Ctrl + C to leave debug repl
 > x
 5
-> 2+2
+> 2 + 2
 4
 debug> next
 break in /home/indutny/Code/git/indutny/myscript.js:5

doc/api/dns.md

@@ -212,7 +212,7 @@ will contain an array of IPv4 addresses (e.g.
 * `options` {Object}
   * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record.
     The callback receives an array of `{ address: '1.2.3.4', ttl: 60 }` objects
-    rather than an array of strings.  The TTL is expressed in seconds.
+    rather than an array of strings. The TTL is expressed in seconds.
 * `callback` {Function} An `(err, result)` callback function.
 
 ## dns.resolve6(hostname[, options], callback)
@@ -228,7 +228,7 @@ will contain an array of IPv6 addresses.
 * `options` {Object}
   * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record.
     The callback receives an array of `{ address: '0:1:2:3:4:5:6:7', ttl: 60 }`
-    objects rather than an array of strings.  The TTL is expressed in seconds.
+    objects rather than an array of strings. The TTL is expressed in seconds.
 * `callback` {Function} An `(err, result)` callback function.
 
 ## dns.resolveCname(hostname, callback)
@@ -258,7 +258,7 @@ added: v0.9.12
 
 Uses the DNS protocol to resolve regular expression based records (`NAPTR`
 records) for the `hostname`. The `callback` function has arguments
-`(err, addresses)`.  The `addresses` argument passed to the `callback` function
+`(err, addresses)`. The `addresses` argument passed to the `callback` function
 will contain an array of objects with the following properties:
 
 * `flags`

doc/api/documentation.md

@@ -26,10 +26,10 @@ using the `tools/doc/generate.js` program. An HTML template is located at
 <!--type=misc-->
 
 Throughout the documentation, you will see indications of a section's
-stability.  The Node.js API is still somewhat changing, and as it
-matures, certain parts are more reliable than others.  Some are so
+stability. The Node.js API is still somewhat changing, and as it
+matures, certain parts are more reliable than others. Some are so
 proven, and so relied upon, that they are unlikely to ever change at
-all.  Others are brand new and experimental, or known to be hazardous
+all. Others are brand new and experimental, or known to be hazardous
 and in the process of being redesigned.
 
 The stability indices are as follows:

doc/api/domain.md

@@ -12,7 +12,7 @@ but should expect to have to migrate to a different solution
 in the future.
 
 Domains provide a way to handle multiple different IO operations as a
-single group.  If any of the event emitters or callbacks registered to a
+single group. If any of the event emitters or callbacks registered to a
 domain emit an `'error'` event, or throw an error, then the domain object
 will be notified, rather than losing the context of the error in the
 `process.on('uncaughtException')` handler, or causing the program to
@@ -30,7 +30,7 @@ never any way to safely "pick up where you left off", without leaking
 references, or creating some other sort of undefined brittle state.
 
 The safest way to respond to a thrown error is to shut down the
-process.  Of course, in a normal web server, you might have many
+process. Of course, in a normal web server, you might have many
 connections open, and it is not reasonable to abruptly shut those down
 because an error was triggered by someone else.
 
@@ -40,7 +40,7 @@ time, and stop listening for new requests in that worker.
 
 In this way, `domain` usage goes hand-in-hand with the cluster module,
 since the master process can fork a new worker when a worker
-encounters an error.  For Node.js programs that scale to multiple
+encounters an error. For Node.js programs that scale to multiple
 machines, the terminating proxy or service registry can take note of
 the failure, and react accordingly.
 
@@ -103,7 +103,7 @@ if (cluster.isMaster) {
   const domain = require('domain');
 
   // See the cluster documentation for more details about using
-  // worker processes to serve requests.  How it works, caveats, etc.
+  // worker processes to serve requests. How it works, caveats, etc.
 
   const server = require('http').createServer((req, res) => {
     const d = domain.create();
@@ -126,7 +126,7 @@ if (cluster.isMaster) {
         // stop taking new requests.
         server.close();
 
-        // Let the master know we're dead.  This will trigger a
+        // Let the master know we're dead. This will trigger a
         // 'disconnect' in the cluster master, and then it will fork
         // a new worker.
         cluster.worker.disconnect();
@@ -155,7 +155,7 @@ if (cluster.isMaster) {
   server.listen(PORT);
 }
 
-// This part is not important.  Just an example routing thing.
+// This part is not important. Just an example routing thing.
 // You'd put your fancy application logic here.
 function handleRequest(req, res) {
   switch (req.url) {
@@ -197,11 +197,11 @@ the active domain at the time of their creation.
 
 Additionally, callbacks passed to lowlevel event loop requests (such as
 to fs.open, or other callback-taking methods) will automatically be
-bound to the active domain.  If they throw, then the domain will catch
+bound to the active domain. If they throw, then the domain will catch
 the error.
 
 In order to prevent excessive memory usage, Domain objects themselves
-are not implicitly added as children of the active domain.  If they
+are not implicitly added as children of the active domain. If they
 were, then it would be too easy to prevent request and response objects
 from being properly garbage collected.
 
@@ -218,7 +218,7 @@ Implicit binding only takes care of thrown errors and `'error'` events.
 <!--type=misc-->
 
 Sometimes, the domain in use is not the one that ought to be used for a
-specific event emitter.  Or, the event emitter could have been created
+specific event emitter. Or, the event emitter could have been created
 in the context of one domain, but ought to instead be bound to some
 other domain.
 
@@ -268,7 +268,7 @@ Returns a new Domain object.
 The Domain class encapsulates the functionality of routing errors and
 uncaught exceptions to the active Domain object.
 
-Domain is a child class of [`EventEmitter`][].  To handle the errors that it
+Domain is a child class of [`EventEmitter`][]. To handle the errors that it
 catches, listen to its `'error'` event.
 
 ### domain.run(fn[, ...args])
@@ -318,13 +318,13 @@ to the domain.
 
 * `emitter` {EventEmitter|Timer} emitter or timer to be added to the domain
 
-Explicitly adds an emitter to the domain.  If any event handlers called by
+Explicitly adds an emitter to the domain. If any event handlers called by
 the emitter throw an error, or if the emitter emits an `'error'` event, it
 will be routed to the domain's `'error'` event, just like with implicit
 binding.
 
 This also works with timers that are returned from [`setInterval()`][] and
-[`setTimeout()`][].  If their callback function throws, it will be caught by
+[`setTimeout()`][]. If their callback function throws, it will be caught by
 the domain 'error' handler.
 
 If the Timer or EventEmitter was already bound to a domain, it is removed
@@ -334,7 +334,7 @@ from that one, and bound to this one instead.
 
 * `emitter` {EventEmitter|Timer} emitter or timer to be removed from the domain
 
-The opposite of [`domain.add(emitter)`][].  Removes domain handling from the
+The opposite of [`domain.add(emitter)`][]. Removes domain handling from the
 specified emitter.
 
 ### domain.bind(callback)
@@ -343,7 +343,7 @@ specified emitter.
 * Returns: {Function} The bound function
 
 The returned function will be a wrapper around the supplied callback
-function.  When the returned function is called, any errors that are
+function. When the returned function is called, any errors that are
 thrown will be routed to the domain's `'error'` event.
 
 #### Example
@@ -370,7 +370,7 @@ d.on('error', (er) => {
 * `callback` {Function} The callback function
 * Returns: {Function} The intercepted function
 
-This method is almost identical to [`domain.bind(callback)`][].  However, in
+This method is almost identical to [`domain.bind(callback)`][]. However, in
 addition to catching thrown errors, it will also intercept [`Error`][]
 objects sent as the first argument to the function.
 
@@ -439,7 +439,7 @@ without exiting the domain.
 
 ### domain.dispose()
 
-> Stability: 0 - Deprecated.  Please recover from failed IO actions
+> Stability: 0 - Deprecated. Please recover from failed IO actions
 > explicitly via error event handlers set on the domain.
 
 Once `dispose` has been called, the domain will no longer be used by callbacks