Skip to content

Commit

Permalink
doc: fix various nits
Browse files Browse the repository at this point in the history
* 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.

PR-URL: #19743
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
  • Loading branch information
vsemozhetbyt authored and targos committed Apr 4, 2018
1 parent 0bd78dc commit ae86adc
Show file tree
Hide file tree
Showing 34 changed files with 268 additions and 267 deletions.
2 changes: 1 addition & 1 deletion doc/api/addons.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,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 the 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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/async_hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -636,7 +636,7 @@ asyncResource.emitAfter();
* `type` {string} The type of async event.
* `options` {Object}
* `triggerAsyncId` {number} The ID of the execution context that created this
async event. **Default:** `executionAsyncId()`
async event. **Default:** `executionAsyncId()`.
* `requireManualDestroy` {boolean} Disables automatic `emitDestroy` when the
object is garbage collected. This usually does not need to be set (even if
`emitDestroy` is called manually), unless the resource's asyncId is retrieved
Expand Down
12 changes: 6 additions & 6 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ differently based on what arguments are provided:
entire `Buffer`. While this behavior is *intentional* to improve performance,
development experience has demonstrated that a more explicit distinction is
required between creating a fast-but-uninitialized `Buffer` versus creating a
slower-but-safer `Buffer`. Starting in Node.js 8.0.0, `Buffer(num)` and
slower-but-safer `Buffer`. Starting in Node.js 8.0.0, `Buffer(num)` and
`new Buffer(num)` will return a `Buffer` with initialized memory.
* Passing a string, array, or `Buffer` as the first argument copies the
passed object's data into the `Buffer`.
Expand Down Expand Up @@ -426,7 +426,7 @@ changes:
* `size` {integer} The desired length of the new `Buffer`.

Allocates a new `Buffer` of `size` bytes. If the `size` is larger than
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
thrown. A zero-length `Buffer` will be created if `size` is 0.

Expand Down Expand Up @@ -502,7 +502,7 @@ console.log(buf);
// Prints: <Buffer 00 00 00 00 00>
```

Allocates a new `Buffer` of `size` bytes. If the `size` is larger than
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
thrown. A zero-length `Buffer` will be created if `size` is 0.

Expand Down Expand Up @@ -543,7 +543,7 @@ changes:

* `size` {integer} The desired length of the new `Buffer`.

Allocates a new `Buffer` of `size` bytes. If the `size` is larger than
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
thrown. A zero-length `Buffer` will be created if `size` is 0.

Expand Down Expand Up @@ -587,7 +587,7 @@ added: v5.12.0

* `size` {integer} The desired length of the new `Buffer`.

Allocates a new `Buffer` of `size` bytes. If the `size` is larger than
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
thrown. A zero-length `Buffer` will be created if `size` is 0.

Expand Down Expand Up @@ -2458,7 +2458,7 @@ deprecated: v6.0.0
* `size` {integer} The desired length of the new `SlowBuffer`.

Allocates a new `Buffer` of `size` bytes. If the `size` is larger than
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
thrown. A zero-length `Buffer` will be created if `size` is 0.

Expand Down
35 changes: 18 additions & 17 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,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,
Expand Down Expand Up @@ -146,8 +146,8 @@ changes:
[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.
See caveat at [`maxBuffer` and Unicode][].
stderr. If exceeded, the child process is terminated. See caveat at
[`maxBuffer` and Unicode][]. **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)).
Expand Down Expand Up @@ -189,7 +189,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
Expand Down Expand Up @@ -258,8 +258,8 @@ changes:
* `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.
See caveat at [`maxBuffer` and Unicode][].
stderr. If exceeded, the child process is terminated. See caveat at
[`maxBuffer` and Unicode][]. **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)).
Expand Down Expand Up @@ -538,7 +538,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()`
Expand Down Expand Up @@ -712,9 +712,10 @@ changes:
* `killSignal` {string|integer} The signal value to be used when the spawned
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.
See caveat at [`maxBuffer` and Unicode][].
* `encoding` {string} The encoding used for all stdio inputs and outputs. **Default:** `'buffer'`
stderr. If exceeded, the child process is terminated. See caveat at
[`maxBuffer` and Unicode][]. **Default:** `200 * 1024`.
* `encoding` {string} The encoding used for all stdio inputs and outputs.
**Default:** `'buffer'`.
* `windowsHide` {boolean} Hide the subprocess console window that would
normally be created on Windows systems. **Default:** `false`.
* `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses
Expand Down Expand Up @@ -773,8 +774,8 @@ changes:
* `killSignal` {string|integer} The signal value to be used when the spawned
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.
See caveat at [`maxBuffer` and Unicode][].
stderr. If exceeded, the child process is terminated. See caveat at
[`maxBuffer` and Unicode][]. **Default:** `200 * 1024`.
* `encoding` {string} The encoding used for all stdio inputs and outputs.
**Default:** `'buffer'`
* `windowsHide` {boolean} Hide the subprocess console window that would
Expand All @@ -785,12 +786,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()`][]

**Never pass unsanitized user input to this function. Any input containing shell
Expand Down Expand Up @@ -830,8 +831,8 @@ changes:
* `killSignal` {string|integer} The signal value to be used when the spawned
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.
See caveat at [`maxBuffer` and Unicode][].
stderr. If exceeded, the child process is terminated. See caveat at
[`maxBuffer` and Unicode][]. **Default:** `200 * 1024`.
* `encoding` {string} The encoding used for all stdio inputs and outputs.
**Default:** `'buffer'`
* `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses
Expand Down Expand Up @@ -1168,7 +1169,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
Expand Down
4 changes: 2 additions & 2 deletions doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -517,7 +517,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_EXTRA_CA_CERTS=file`
Expand Down Expand Up @@ -602,7 +602,7 @@ reason any of these APIs takes a long time, other (seemingly unrelated) APIs
that run in libuv's threadpool will experience degraded performance. In order to
mitigate this issue, one potential solution is to increase the size of libuv's
threadpool by setting the `'UV_THREADPOOL_SIZE'` environment variable to a value
greater than `4` (its current default value). For more information, see the
greater than `4` (its current default value). For more information, see the
[libuv threadpool documentation][].

[`--openssl-config`]: #cli_openssl_config_file
Expand Down
14 changes: 7 additions & 7 deletions doc/api/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ Node.js process and a cluster worker differs:
process.
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
same "random" port each time they do `listen(0)`. In essence, the
port is random the first time, but predictable thereafter. To listen
on a unique port, generate a port number based on the cluster worker ID.

Expand All @@ -103,8 +103,8 @@ things like sessions and login.

Because workers are all separate processes, they can be killed or
re-spawned depending on a 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
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, however. It is the application's
responsibility to manage the worker pool based on its own needs.
Expand Down Expand Up @@ -465,8 +465,8 @@ 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 can be used to detect if the process is stuck in a cleanup or if there
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.

```js
Expand Down Expand Up @@ -556,7 +556,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'
<!-- YAML
Expand Down Expand Up @@ -692,7 +692,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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/console.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,7 @@ Updates the cipher with `data`. If the `inputEncoding` argument is given,
its value must be one of `'utf8'`, `'ascii'`, or `'latin1'` and the `data`
argument is a string using the specified encoding. If the `inputEncoding`
argument is not given, `data` must be a [`Buffer`][], `TypedArray`, or
`DataView`. If `data` is a [`Buffer`][], `TypedArray`, or `DataView`, then
`DataView`. If `data` is a [`Buffer`][], `TypedArray`, or `DataView`, then
`inputEncoding` is ignored.

The `outputEncoding` specifies the output format of the enciphered
Expand Down Expand Up @@ -552,7 +552,7 @@ added: v0.5.0
- `encoding` {string}

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])
Expand Down Expand Up @@ -1716,8 +1716,8 @@ const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
console.log(key.toString('hex')); // '3745e48...08d59ae'
```

The `crypto.DEFAULT_ENCODING` may be used to change the way the `derivedKey`
is returned:
The `crypto.DEFAULT_ENCODING` property may be used to change the way the
`derivedKey` is returned.

```js
const crypto = require('crypto');
Expand Down
2 changes: 1 addition & 1 deletion doc/api/debugger.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ debug> repl
Press Ctrl + C to leave debug repl
> x
5
> 2+2
> 2 + 2
4
debug> next
< world
Expand Down
4 changes: 2 additions & 2 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -699,8 +699,8 @@ Type: Runtime
`Module._debug()` has been deprecated.
The `Module._debug()` function was never documented as an officially supported
API.
The `Module._debug()` function was never documented as an officially
supported API.
<a id="DEP0078"></a>
### DEP0078: REPLServer.turnOffEditorMode()
Expand Down
Loading

0 comments on commit ae86adc

Please sign in to comment.