Skip to content

Commit

Permalink
doc: add explicit bracket for markdown reference links
Browse files Browse the repository at this point in the history
Use explicit trailing `[]` for reference markdown links to prevent
implicit links when references are added to documents.

PR-URL: #29808
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
  • Loading branch information
nschonni authored and BridgeAR committed Oct 9, 2019
1 parent b2cce13 commit a5c2154
Show file tree
Hide file tree
Showing 17 changed files with 92 additions and 90 deletions.
6 changes: 3 additions & 3 deletions doc/api/assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,9 @@ All instances contain the built-in `Error` properties (`message` and `name`)
and:

* `actual` {any} Set to the `actual` argument for methods such as
[`assert.strictEqual()`].
[`assert.strictEqual()`][].
* `expected` {any} Set to the `expected` value for methods such as
[`assert.strictEqual()`].
[`assert.strictEqual()`][].
* `generatedMessage` {boolean} Indicates if the message was auto-generated
(`true`) or not.
* `code` {string} Value is always `ERR_ASSERTION` to show that the error is an
Expand Down Expand Up @@ -638,7 +638,7 @@ If `message` is falsy, the error message is set as the values of `actual` and
`message` is provided as third argument it will be used as the error message and
the other arguments will be stored as properties on the thrown object. If
`stackStartFn` is provided, all stack frames above that function will be
removed from stacktrace (see [`Error.captureStackTrace`]). If no arguments are
removed from stacktrace (see [`Error.captureStackTrace`][]). If no arguments are
given, the default message `Failed` will be used.

```js
Expand Down
4 changes: 2 additions & 2 deletions doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -2076,7 +2076,7 @@ and Ed448 are currently supported.

If a `publicKeyEncoding` or `privateKeyEncoding` was specified, this function
behaves as if [`keyObject.export()`][] had been called on its result. Otherwise,
the respective part of the key is returned as a [`KeyObject`].
the respective part of the key is returned as a [`KeyObject`][].

It is recommended to encode public keys as `'spki'` and private keys as
`'pkcs8'` with encryption for long-term storage:
Expand Down Expand Up @@ -2136,7 +2136,7 @@ and Ed448 are currently supported.

If a `publicKeyEncoding` or `privateKeyEncoding` was specified, this function
behaves as if [`keyObject.export()`][] had been called on its result. Otherwise,
the respective part of the key is returned as a [`KeyObject`].
the respective part of the key is returned as a [`KeyObject`][].

When encoding public keys, it is recommended to use `'spki'`. When encoding
private keys, it is recommended to use `'pks8'` with a strong passphrase, and to
Expand Down
4 changes: 2 additions & 2 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -2505,8 +2505,8 @@ changes:
Type: Documentation-only
Prefer [`response.socket`][] over [`response.connection`] and
[`request.socket`][] over [`request.connection`].
Prefer [`response.socket`][] over [`response.connection`][] and
[`request.socket`][] over [`request.connection`][].
<a id="DEP0134"></a>
### DEP0134: process._tickCallback
Expand Down
18 changes: 9 additions & 9 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -461,7 +461,7 @@ system error.

The `error.errno` property is a number or a string. If it is a number, it is a
negative value which corresponds to the error code defined in
[`libuv Error handling`]. See the libuv `errno.h` header file
[`libuv Error handling`][]. See the libuv `errno.h` header file
(`deps/uv/include/uv/errno.h` in the Node.js source tree) for details. In case
of a string, it is the same as `error.code`.

Expand Down Expand Up @@ -1283,8 +1283,8 @@ semantics for determining whether a path can be used is platform-dependent.
### ERR_INVALID_HANDLE_TYPE

An attempt was made to send an unsupported "handle" over an IPC communication
channel to a child process. See [`subprocess.send()`] and [`process.send()`] for
more information.
channel to a child process. See [`subprocess.send()`][] and [`process.send()`][]
for more information.

<a id="ERR_INVALID_HTTP_TOKEN"></a>
### ERR_INVALID_HTTP_TOKEN
Expand Down Expand Up @@ -1436,36 +1436,36 @@ for more information.
### ERR_MANIFEST_ASSERT_INTEGRITY

An attempt was made to load a resource, but the resource did not match the
integrity defined by the policy manifest. See the documentation for [policy]
integrity defined by the policy manifest. See the documentation for [policy][]
manifests for more information.

<a id="ERR_MANIFEST_DEPENDENCY_MISSING"></a>
### ERR_MANIFEST_DEPENDENCY_MISSING

An attempt was made to load a resource, but the resource was not listed as a
dependency from the location that attempted to load it. See the documentation
for [policy] manifests for more information.
for [policy][] manifests for more information.

<a id="ERR_MANIFEST_INTEGRITY_MISMATCH"></a>
### ERR_MANIFEST_INTEGRITY_MISMATCH

An attempt was made to load a policy manifest, but the manifest had multiple
entries for a resource which did not match each other. Update the manifest
entries to match in order to resolve this error. See the documentation for
[policy] manifests for more information.
[policy][] manifests for more information.

<a id="ERR_MANIFEST_INVALID_RESOURCE_FIELD"></a>
### ERR_MANIFEST_INVALID_RESOURCE_FIELD

A policy manifest resource had an invalid value for one of its fields. Update
the manifest entry to match in order to resolve this error. See the
documentation for [policy] manifests for more information.
documentation for [policy][] manifests for more information.

<a id="ERR_MANIFEST_PARSE_POLICY"></a>
### ERR_MANIFEST_PARSE_POLICY

An attempt was made to load a policy manifest, but the manifest was unable to
be parsed. See the documentation for [policy] manifests for more information.
be parsed. See the documentation for [policy][] manifests for more information.

<a id="ERR_MANIFEST_TDZ"></a>
### ERR_MANIFEST_TDZ
Expand All @@ -1477,7 +1477,7 @@ initialization has not yet taken place. This is likely a bug in Node.js.
### ERR_MANIFEST_UNKNOWN_ONERROR

A policy manifest was loaded, but had an unknown value for its "onerror"
behavior. See the documentation for [policy] manifests for more information.
behavior. See the documentation for [policy][] manifests for more information.

<a id="ERR_MEMORY_ALLOCATION_FAILED"></a>
### ERR_MEMORY_ALLOCATION_FAILED
Expand Down
15 changes: 8 additions & 7 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -3133,7 +3133,7 @@ Using `fs.stat()` to check for the existence of a file before calling
Instead, user code should open/read/write the file directly and handle the
error raised if the file is not available.

To check if a file exists without manipulating it afterwards, [`fs.access()`]
To check if a file exists without manipulating it afterwards, [`fs.access()`][]
is recommended.

For example, given the following folder structure:
Expand Down Expand Up @@ -3541,12 +3541,13 @@ The recursive option is only supported on macOS and Windows.
This feature depends on the underlying operating system providing a way
to be notified of filesystem changes.

* On Linux systems, this uses [`inotify(7)`].
* On BSD systems, this uses [`kqueue(2)`].
* On macOS, this uses [`kqueue(2)`] for files and [`FSEvents`] for directories.
* On SunOS systems (including Solaris and SmartOS), this uses [`event ports`].
* On Windows systems, this feature depends on [`ReadDirectoryChangesW`].
* On Aix systems, this feature depends on [`AHAFS`], which must be enabled.
* On Linux systems, this uses [`inotify(7)`][].
* On BSD systems, this uses [`kqueue(2)`][].
* On macOS, this uses [`kqueue(2)`][] for files and [`FSEvents`][] for
directories.
* On SunOS systems (including Solaris and SmartOS), this uses [`event ports`][].
* On Windows systems, this feature depends on [`ReadDirectoryChangesW`][].
* On Aix systems, this feature depends on [`AHAFS`][], which must be enabled.

If the underlying functionality is not available for some reason, then
`fs.watch` will not be able to function. For example, watching files or
Expand Down
22 changes: 11 additions & 11 deletions doc/api/globals.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ Used to handle binary data. See the [buffer section][].

## \_\_dirname

This variable may appear to be global but is not. See [`__dirname`].
This variable may appear to be global but is not. See [`__dirname`][].

## \_\_filename

This variable may appear to be global but is not. See [`__filename`].
This variable may appear to be global but is not. See [`__filename`][].

## clearImmediate(immediateObject)
<!-- YAML
Expand All @@ -43,7 +43,7 @@ added: v0.9.1

<!--type=global-->

[`clearImmediate`] is described in the [timers][] section.
[`clearImmediate`][] is described in the [timers][] section.

## clearInterval(intervalObject)
<!-- YAML
Expand All @@ -52,7 +52,7 @@ added: v0.0.1

<!--type=global-->

[`clearInterval`] is described in the [timers][] section.
[`clearInterval`][] is described in the [timers][] section.

## clearTimeout(timeoutObject)
<!-- YAML
Expand All @@ -61,7 +61,7 @@ added: v0.0.1

<!--type=global-->

[`clearTimeout`] is described in the [timers][] section.
[`clearTimeout`][] is described in the [timers][] section.

## console
<!-- YAML
Expand All @@ -76,7 +76,7 @@ Used to print to stdout and stderr. See the [`console`][] section.

## exports

This variable may appear to be global but is not. See [`exports`].
This variable may appear to be global but is not. See [`exports`][].

## global
<!-- YAML
Expand All @@ -94,7 +94,7 @@ Node.js this is different. The top-level scope is not the global scope;

## module

This variable may appear to be global but is not. See [`module`].
This variable may appear to be global but is not. See [`module`][].

## process
<!-- YAML
Expand Down Expand Up @@ -148,7 +148,7 @@ DataHandler.prototype.load = async function load(key) {

## require()

This variable may appear to be global but is not. See [`require()`].
This variable may appear to be global but is not. See [`require()`][].

## setImmediate(callback[, ...args])
<!-- YAML
Expand All @@ -157,7 +157,7 @@ added: v0.9.1

<!-- type=global -->

[`setImmediate`] is described in the [timers][] section.
[`setImmediate`][] is described in the [timers][] section.

## setInterval(callback, delay[, ...args])
<!-- YAML
Expand All @@ -166,7 +166,7 @@ added: v0.0.1

<!-- type=global -->

[`setInterval`] is described in the [timers][] section.
[`setInterval`][] is described in the [timers][] section.

## setTimeout(callback, delay[, ...args])
<!-- YAML
Expand All @@ -175,7 +175,7 @@ added: v0.0.1

<!-- type=global -->

[`setTimeout`] is described in the [timers][] section.
[`setTimeout`][] is described in the [timers][] section.

## TextDecoder
<!-- YAML
Expand Down
2 changes: 1 addition & 1 deletion doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ the requests to that server, but each one will occur over a new connection.
When a connection is closed by the client or the server, it is removed
from the pool. Any unused sockets in the pool will be unrefed so as not
to keep the Node.js process running when there are no outstanding requests.
(see [`socket.unref()`]).
(see [`socket.unref()`][]).

It is good practice, to [`destroy()`][] an `Agent` instance when it is no
longer in use, because unused sockets consume OS resources.
Expand Down
10 changes: 5 additions & 5 deletions doc/api/http2.md
Original file line number Diff line number Diff line change
Expand Up @@ -500,7 +500,7 @@ added: v9.4.0
-->

Calls [`ref()`][`net.Socket.prototype.ref()`] on this `Http2Session`
instance's underlying [`net.Socket`].
instance's underlying [`net.Socket`][].

#### http2session.remoteSettings
<!-- YAML
Expand Down Expand Up @@ -613,7 +613,7 @@ added: v9.4.0
-->

Calls [`unref()`][`net.Socket.prototype.unref()`] on this `Http2Session`
instance's underlying [`net.Socket`].
instance's underlying [`net.Socket`][].

### Class: ServerHttp2Session
<!-- YAML
Expand Down Expand Up @@ -1756,7 +1756,7 @@ added: v8.4.0

Stops the server from establishing new sessions. This does not prevent new
request streams from being created due to the persistent nature of HTTP/2
sessions. To gracefully shut down the server, call [`http2session.close()`] on
sessions. To gracefully shut down the server, call [`http2session.close()`][] on
all active sessions.

If `callback` is provided, it is not invoked until all active sessions have been
Expand Down Expand Up @@ -1905,7 +1905,7 @@ added: v8.4.0

Stops the server from establishing new sessions. This does not prevent new
request streams from being created due to the persistent nature of HTTP/2
sessions. To gracefully shut down the server, call [`http2session.close()`] on
sessions. To gracefully shut down the server, call [`http2session.close()`][] on
all active sessions.

If `callback` is provided, it is not invoked until all active sessions have been
Expand Down Expand Up @@ -3420,7 +3420,7 @@ added: v8.4.0
* `stream` {ServerHttp2Stream} The newly-created `ServerHttp2Stream` object

Call [`http2stream.pushStream()`][] with the given headers, and wrap the
given [`Http2Stream`] on a newly created `Http2ServerResponse` as the callback
given [`Http2Stream`][] on a newly created `Http2ServerResponse` as the callback
parameter if successful. When `Http2ServerRequest` is closed, the callback is
called with an error `ERR_HTTP2_INVALID_STREAM`.

Expand Down
2 changes: 1 addition & 1 deletion doc/api/inspector.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ added: v8.0.0
-->

Immediately close the session. All pending message callbacks will be called
with an error. [`session.connect()`] will need to be called to be able to send
with an error. [`session.connect()`][] will need to be called to be able to send
messages again. Reconnected session will lose all inspector state, such as
enabled agents or configured breakpoints.

Expand Down
10 changes: 5 additions & 5 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ all `'exit'` listeners have finished running the Node.js process will terminate.

The listener callback function is invoked with the exit code specified either
by the [`process.exitCode`][] property, or the `exitCode` argument passed to the
[`process.exit()`] method.
[`process.exit()`][] method.

```js
process.on('exit', (code) => {
Expand Down Expand Up @@ -570,8 +570,8 @@ added: v0.1.27

The `process.argv` property returns an array containing the command line
arguments passed when the Node.js process was launched. The first element will
be [`process.execPath`]. See `process.argv0` if access to the original value of
`argv[0]` is needed. The second element will be the path to the JavaScript
be [`process.execPath`][]. See `process.argv0` if access to the original value
of `argv[0]` is needed. The second element will be the path to the JavaScript
file being executed. The remaining elements will be any additional command line
arguments.

Expand Down Expand Up @@ -1122,7 +1122,7 @@ added: v0.1.13
The `process.exit()` method instructs Node.js to terminate the process
synchronously with an exit status of `code`. If `code` is omitted, exit uses
either the 'success' code `0` or the value of `process.exitCode` if it has been
set. Node.js will not terminate until all the [`'exit'`] event listeners are
set. Node.js will not terminate until all the [`'exit'`][] event listeners are
called.

To exit with a 'failure' code:
Expand Down Expand Up @@ -1506,7 +1506,7 @@ changes:
fully drained after the current operation on the JavaScript stack runs to
completion and before the event loop is allowed to continue. It's possible to
create an infinite loop if one were to recursively call `process.nextTick()`.
See the [Event Loop] guide for more background.
See the [Event Loop][] guide for more background.

```js
console.log('start');
Expand Down
3 changes: 2 additions & 1 deletion doc/api/readline.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
> Stability: 2 - Stable
The `readline` module provides an interface for reading data from a [Readable][]
stream (such as [`process.stdin`]) one line at a time. It can be accessed using:
stream (such as [`process.stdin`][]) one line at a time. It can be accessed
using:

```js
const readline = require('readline');
Expand Down
14 changes: 7 additions & 7 deletions doc/api/stream.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ total size of the internal write buffer is below the threshold set by
the size of the internal buffer reaches or exceeds the `highWaterMark`, `false`
will be returned.

A key goal of the `stream` API, particularly the [`stream.pipe()`] method,
A key goal of the `stream` API, particularly the [`stream.pipe()`][] method,
is to limit the buffering of data to acceptable levels such that sources and
destinations of differing speeds will not overwhelm the available memory.

Expand Down Expand Up @@ -682,7 +682,7 @@ from the stream.

Adding a [`'readable'`][] event handler automatically make the stream to
stop flowing, and the data to be consumed via
[`readable.read()`][stream-read]. If the [`'readable'`] event handler is
[`readable.read()`][stream-read]. If the [`'readable'`][] event handler is
removed, then the stream will start flowing again if there is a
[`'data'`][] event handler.

Expand Down Expand Up @@ -1653,10 +1653,10 @@ on the type of stream being created, as detailed in the chart below:

| Use-case | Class | Method(s) to implement |
| -------- | ----- | ---------------------- |
| Reading only | [`Readable`] | <code>[_read()][stream-_read]</code> |
| Writing only | [`Writable`] | <code>[_write()][stream-_write]</code>, <code>[_writev()][stream-_writev]</code>, <code>[_final()][stream-_final]</code> |
| Reading and writing | [`Duplex`] | <code>[_read()][stream-_read]</code>, <code>[_write()][stream-_write]</code>, <code>[_writev()][stream-_writev]</code>, <code>[_final()][stream-_final]</code> |
| Operate on written data, then read the result | [`Transform`] | <code>[_transform()][stream-_transform]</code>, <code>[_flush()][stream-_flush]</code>, <code>[_final()][stream-_final]</code> |
| Reading only | [`Readable`][] | [`_read()`][stream-_read] |
| Writing only | [`Writable`][] | [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] |
| Reading and writing | [`Duplex`][] | [`_read()`][stream-_read], [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] |
| Operate on written data, then read the result | [`Transform`][] | [`_transform()`][stream-_transform], [`_flush()`][stream-_flush], [`_final()`][stream-_final] |

The implementation code for a stream should *never* call the "public" methods
of a stream that are intended for use by consumers (as described in the
Expand Down Expand Up @@ -1881,7 +1881,7 @@ or write buffered data before a stream ends.
#### Errors While Writing

Errors occurring during the processing of the [`writable._write()`][],
[`writable._writev()`][] and [`writable._final()`] methods must be propagated
[`writable._writev()`][] and [`writable._final()`][] methods must be propagated
by invoking the callback and passing the error as the first argument.
Throwing an `Error` from within these methods or manually emitting an `'error'`
event results in undefined behavior.
Expand Down
Loading

0 comments on commit a5c2154

Please sign in to comment.