Skip to content

Commit

Permalink
doc: remove dashes
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
Trott authored and targos committed Oct 28, 2019
1 parent 4458378 commit 45c70a9
Show file tree
Hide file tree
Showing 26 changed files with 266 additions and 274 deletions.
7 changes: 3 additions & 4 deletions doc/api/addons.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
20 changes: 10 additions & 10 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
26 changes: 13 additions & 13 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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'`.

Expand Down
2 changes: 1 addition & 1 deletion doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
16 changes: 8 additions & 8 deletions doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
44 changes: 22 additions & 22 deletions doc/api/debugger.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
12 changes: 6 additions & 6 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions doc/api/dgram.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand All @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/esm.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit 45c70a9

Please sign in to comment.