From a5c2154534aa5342e4ec7842c8cb6678d2f3444c Mon Sep 17 00:00:00 2001 From: Nick Schonning Date: Wed, 2 Oct 2019 00:31:57 -0400 Subject: [PATCH] doc: add explicit bracket for markdown reference links Use explicit trailing `[]` for reference markdown links to prevent implicit links when references are added to documents. PR-URL: https://github.com/nodejs/node/pull/29808 Reviewed-By: Ruben Bridgewater Reviewed-By: David Carlier Reviewed-By: Colin Ihrig --- doc/api/assert.md | 6 +++--- doc/api/crypto.md | 4 ++-- doc/api/deprecations.md | 4 ++-- doc/api/errors.md | 18 ++++++++-------- doc/api/fs.md | 15 +++++++------- doc/api/globals.md | 22 ++++++++++---------- doc/api/http.md | 2 +- doc/api/http2.md | 10 ++++----- doc/api/inspector.md | 2 +- doc/api/process.md | 10 ++++----- doc/api/readline.md | 3 ++- doc/api/stream.md | 14 ++++++------- doc/api/timers.md | 2 +- doc/api/tls.md | 40 ++++++++++++++++++------------------ doc/api/tracing.md | 8 ++++---- doc/api/util.md | 2 +- doc/guides/maintaining-V8.md | 20 +++++++++--------- 17 files changed, 92 insertions(+), 90 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 2c74b6809e1a45..68feec9f45212e 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -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 @@ -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 diff --git a/doc/api/crypto.md b/doc/api/crypto.md index ba1582bd78d542..0c98506f1b48b1 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -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: @@ -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 diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 08e4ec065a992a..9687f342b46141 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -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`][]. ### DEP0134: process._tickCallback diff --git a/doc/api/errors.md b/doc/api/errors.md index 2ba78a95cf2550..4b92452cd362a0 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -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`. @@ -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. ### ERR_INVALID_HTTP_TOKEN @@ -1436,7 +1436,7 @@ 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. @@ -1444,7 +1444,7 @@ manifests for more information. 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. ### ERR_MANIFEST_INTEGRITY_MISMATCH @@ -1452,20 +1452,20 @@ for [policy] manifests for more information. 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. ### 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. ### 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. ### ERR_MANIFEST_TDZ @@ -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. ### ERR_MEMORY_ALLOCATION_FAILED diff --git a/doc/api/fs.md b/doc/api/fs.md index 7ea6835387719b..c22e169f1c3937 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -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: @@ -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 diff --git a/doc/api/globals.md b/doc/api/globals.md index f3263c22e73644..89592b98e1c9bf 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -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) -[`clearImmediate`] is described in the [timers][] section. +[`clearImmediate`][] is described in the [timers][] section. ## clearInterval(intervalObject) -[`clearInterval`] is described in the [timers][] section. +[`clearInterval`][] is described in the [timers][] section. ## clearTimeout(timeoutObject) -[`clearTimeout`] is described in the [timers][] section. +[`clearTimeout`][] is described in the [timers][] section. ## console -[`setImmediate`] is described in the [timers][] section. +[`setImmediate`][] is described in the [timers][] section. ## setInterval(callback, delay[, ...args]) -[`setInterval`] is described in the [timers][] section. +[`setInterval`][] is described in the [timers][] section. ## setTimeout(callback, delay[, ...args]) -[`setTimeout`] is described in the [timers][] section. +[`setTimeout`][] is described in the [timers][] section. ## TextDecoder Calls [`ref()`][`net.Socket.prototype.ref()`] on this `Http2Session` -instance's underlying [`net.Socket`]. +instance's underlying [`net.Socket`][]. #### http2session.remoteSettings Calls [`unref()`][`net.Socket.prototype.unref()`] on this `Http2Session` -instance's underlying [`net.Socket`]. +instance's underlying [`net.Socket`][]. ### Class: ServerHttp2Session 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. diff --git a/doc/api/process.md b/doc/api/process.md index ae0dd86bc00548..5ecd5b513f3543 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -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) => { @@ -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. @@ -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: @@ -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'); diff --git a/doc/api/readline.md b/doc/api/readline.md index 898d7e005fb652..03fdc4417230cf 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -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'); diff --git a/doc/api/stream.md b/doc/api/stream.md index eb4b0b82740a8f..4bdf3159dfaa80 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -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. @@ -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. @@ -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`] | [_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] | +| 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 @@ -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. diff --git a/doc/api/timers.md b/doc/api/timers.md index 66ee2ca97e8455..a99dd1c41e60b0 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -136,7 +136,7 @@ added: v0.9.1 --> * `callback` {Function} The function to call at the end of this turn of - [the Node.js Event Loop] + the Node.js [Event Loop][] * `...args` {any} Optional arguments to pass when the `callback` is called. * Returns: {Immediate} for use with [`clearImmediate()`][] diff --git a/doc/api/tls.md b/doc/api/tls.md index 297c1e7fd460dc..d90affa4c3b70d 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -68,12 +68,12 @@ Where: -The term "[Forward Secrecy]" or "Perfect Forward Secrecy" describes a feature of -key-agreement (i.e., key-exchange) methods. That is, the server and client keys -are used to negotiate new temporary keys that are used specifically and only for -the current communication session. Practically, this means that even if the -server's private key is compromised, communication can only be decrypted by -eavesdroppers if the attacker manages to obtain the key-pair specifically +The term "[Forward Secrecy][]" or "Perfect Forward Secrecy" describes a feature +of key-agreement (i.e., key-exchange) methods. That is, the server and client +keys are used to negotiate new temporary keys that are used specifically and +only for the current communication session. Practically, this means that even +if the server's private key is compromised, communication can only be decrypted +by eavesdroppers if the attacker manages to obtain the key-pair specifically generated for the session. Perfect Forward Secrecy is achieved by randomly generating a key pair for @@ -83,8 +83,8 @@ all sessions). Methods implementing this technique are called "ephemeral". Currently two methods are commonly used to achieve Perfect Forward Secrecy (note the character "E" appended to the traditional abbreviations): -* [DHE] - An ephemeral version of the Diffie Hellman key-agreement protocol. -* [ECDHE] - An ephemeral version of the Elliptic Curve Diffie Hellman +* [DHE][] - An ephemeral version of the Diffie Hellman key-agreement protocol. +* [ECDHE][] - An ephemeral version of the Elliptic Curve Diffie Hellman key-agreement protocol. Ephemeral methods may have some performance drawbacks, because key generation @@ -102,7 +102,7 @@ openssl dhparam -outform PEM -out dhparam.pem 2048 If using Perfect Forward Secrecy using `ECDHE`, Diffie-Hellman parameters are not required and a default ECDHE curve will be used. The `ecdhCurve` property can be used when creating a TLS Server to specify the list of names of supported -curves to use, see [`tls.createServer()`] for more info. +curves to use, see [`tls.createServer()`][] for more info. Perfect Forward Secrecy was optional up to TLSv1.2, but it is not optional for TLSv1.3, because all TLSv1.3 cipher suites use ECDHE. @@ -279,8 +279,8 @@ node server.js The default can also be replaced on a per client or server basis using the `ciphers` option from [`tls.createSecureContext()`][], which is also available -in [`tls.createServer()`], [`tls.connect()`], and when creating new -[`tls.TLSSocket`]s. +in [`tls.createServer()`][], [`tls.connect()`][], and when creating new +[`tls.TLSSocket`][]s. The ciphers list can contain a mixture of TLSv1.3 cipher suite names, the ones that start with `'TLS_'`, and specifications for TLSv1.2 and below cipher @@ -303,16 +303,16 @@ of an application. The `--tls-cipher-list` switch and `ciphers` option should by used only if absolutely necessary. The default cipher suite prefers GCM ciphers for [Chrome's 'modern -cryptography' setting] and also prefers ECDHE and DHE ciphers for Perfect +cryptography' setting][] and also prefers ECDHE and DHE ciphers for Perfect Forward Secrecy, while offering *some* backward compatibility. 128 bit AES is preferred over 192 and 256 bit AES in light of [specific -attacks affecting larger AES key sizes]. +attacks affecting larger AES key sizes][]. Old clients that rely on insecure and deprecated RC4 or DES-based ciphers (like Internet Explorer 6) cannot complete the handshaking process with the default configuration. If these clients _must_ be supported, the -[TLS recommendations] may offer a compatible cipher suite. For more details +[TLS recommendations][] may offer a compatible cipher suite. For more details on the format, see the OpenSSL [cipher list format][] documentation. There are only 5 TLSv1.3 cipher suites: @@ -415,7 +415,7 @@ The typical flow of an OCSP Request is as follows: 2. Server receives the request and emits the `'OCSPRequest'` event, calling the listener if registered. 3. Server extracts the OCSP URL from either the `certificate` or `issuer` and - performs an [OCSP request] to the CA. + performs an [OCSP request][] to the CA. 4. Server receives `'OCSPResponse'` from the CA and sends it back to the client via the `callback` argument 5. Client validates the response and either destroys the socket or performs a @@ -428,7 +428,7 @@ via the `ca` option when establishing the TLS connection.) Listening for this event will have an effect only on connections established after the addition of the event listener. -An npm module like [asn1.js] may be used to parse the certificates. +An npm module like [asn1.js][] may be used to parse the certificates. ### Event: 'resumeSession' The default curve name to use for ECDH key agreement in a tls server. The -default value is `'auto'`. See [`tls.createSecureContext()`] for further +default value is `'auto'`. See [`tls.createSecureContext()`][] for further information. ## tls.DEFAULT_MAX_VERSION diff --git a/doc/api/tracing.md b/doc/api/tracing.md index 64622d6b503a56..999c7d723012b0 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -14,8 +14,8 @@ accepts a list of comma-separated category names. The available categories are: * `node` - An empty placeholder. -* `node.async_hooks` - Enables capture of detailed [`async_hooks`] trace data. - The [`async_hooks`] events have a unique `asyncId` and a special `triggerId` +* `node.async_hooks` - Enables capture of detailed [`async_hooks`][] trace data. + The [`async_hooks`][] events have a unique `asyncId` and a special `triggerId` `triggerAsyncId` property. * `node.bootstrap` - Enables capture of Node.js bootstrap milestones. * `node.console` - Enables capture of `console.time()` and `console.count()` @@ -23,7 +23,7 @@ The available categories are: * `node.dns.native` - Enables capture of trace data for DNS queries. * `node.environment` - Enables capture of Node.js Environment milestones. * `node.fs.sync` - Enables capture of trace data for file system sync methods. -* `node.perf` - Enables capture of [Performance API] measurements. +* `node.perf` - Enables capture of [Performance API][] measurements. * `node.perf.usertiming` - Enables capture of only Performance API User Timing measures and marks. * `node.perf.timerify` - Enables capture of only Performance API timerify @@ -32,7 +32,7 @@ The available categories are: of unhandled Promise rejections and handled-after-rejections. * `node.vm.script` - Enables capture of trace data for the `vm` module's `runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. -* `v8` - The [V8] events are GC, compiling, and execution related. +* `v8` - The [V8][] events are GC, compiling, and execution related. By default the `node`, `node.async_hooks`, and `v8` categories are enabled. diff --git a/doc/api/util.md b/doc/api/util.md index d158fbd1a832d7..46df7c01ea7e17 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -1775,7 +1775,7 @@ The `util._extend()` method was never intended to be used outside of internal Node.js modules. The community found and used it anyway. It is deprecated and should not be used in new code. JavaScript comes with very -similar built-in functionality through [`Object.assign()`]. +similar built-in functionality through [`Object.assign()`][]. ### util.isArray(object)