diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 6d41a77e91a3c5..bb7af3f7ec3d43 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -51,10 +51,6 @@ * References to constructor instances should use camelCase. * References to methods should be used with parentheses: for example, `socket.end()` instead of `socket.end`. -* To draw special attention to a note, adhere to the following guidelines: - * Make the "Note:" label italic, i.e. `*Note*:`. - * Use a capital letter after the "Note:" label. - * Preferably, make the note a new paragraph for better visual distinction. * Function arguments or object properties should use the following format: * ``` * `name` {type|type2} Optional description. **Default:** `value`. ``` diff --git a/doc/api/assert.md b/doc/api/assert.md index 4800bed4e8239d..50519b831c9a2c 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -418,10 +418,10 @@ the function does not return a promise, `assert.doesNotReject()` will return a rejected `Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the error handler is skipped. -Please note: Using `assert.doesNotReject()` is actually not useful because there -is little benefit by catching a rejection and then rejecting it again. Instead, -consider adding a comment next to the specific code path that should not reject -and keep error messages as expressive as possible. +Using `assert.doesNotReject()` is actually not useful because there is little +benefit in catching a rejection and then rejecting it again. Instead, consider +adding a comment next to the specific code path that should not reject and keep +error messages as expressive as possible. If specified, `error` can be a [`Class`][], [`RegExp`][] or a validation function. See [`assert.throws()`][] for more details. @@ -464,8 +464,8 @@ changes: Asserts that the function `fn` does not throw an error. -Please note: Using `assert.doesNotThrow()` is actually not useful because there -is no benefit by catching an error and then rethrowing it. Instead, consider +Using `assert.doesNotThrow()` is actually not useful because there +is no benefit in catching an error and then rethrowing it. Instead, consider adding a comment next to the specific code path that should not throw and keep error messages as expressive as possible. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 34b2f521e12ae0..23715b2dd1080f 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1038,9 +1038,9 @@ child process may not actually terminate the process. See kill(2) for reference. -Also note: on Linux, child processes of child processes will not be terminated +On Linux, child processes of child processes will not be terminated when attempting to kill their parent. This is likely to happen when running a -new process in a shell or with use of the `shell` option of `ChildProcess`: +new process in a shell or with the use of the `shell` option of `ChildProcess`: ```js 'use strict'; diff --git a/doc/api/crypto.md b/doc/api/crypto.md index de38522898b82c..4dbdc101018a96 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -848,7 +848,7 @@ const crypto = require('crypto'); const alice = crypto.createECDH('secp256k1'); const bob = crypto.createECDH('secp256k1'); -// Note: This is a shortcut way to specify one of Alice's previous private +// This is a shortcut way of specifying one of Alice's previous private // keys. It would be unwise to use such a predictable private key in a real // application. alice.setPrivateKey( diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 6541959d3adc27..7db8cdf3650342 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -413,7 +413,7 @@ added: v8.6.0 * `multicastInterface` {string} -*Note: All references to scope in this section are referring to +*All references to scope in this section are referring to [IPv6 Zone Indices][], which are defined by [RFC 4007][]. In string form, an IP with a scope index is written as `'IP%scope'` where scope is an interface name or interface number.* diff --git a/doc/api/domain.md b/doc/api/domain.md index 3cd021f9d43ad8..eec763600e228f 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -122,7 +122,7 @@ if (cluster.isMaster) { d.on('error', (er) => { console.error(`error ${er.stack}`); - // Note: We're in dangerous territory! + // We're in dangerous territory! // By definition, something unexpected occurred, // which we probably didn't want. // Anything can happen now! Be very careful! diff --git a/doc/api/path.md b/doc/api/path.md index c04bff0c476f46..a5cd310690e5cc 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -54,7 +54,7 @@ path.posix.basename('/tmp/myfile.html'); // Returns: 'myfile.html' ``` -*Note:* On Windows Node.js follows the concept of per-drive working directory. +On Windows Node.js follows the concept of per-drive working directory. This behavior can be observed when using a drive path without a backslash. For example, `path.resolve('c:\\')` can potentially return a different result than `path.resolve('c:')`. For more information, see diff --git a/doc/api/vm.md b/doc/api/vm.md index f05a767450af52..543f1642f0ff62 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -7,7 +7,7 @@ The `vm` module provides APIs for compiling and running code within V8 Virtual -Machine contexts. **Note that the `vm` module is not a security mechanism. Do +Machine contexts. **The `vm` module is not a security mechanism. Do not use it to run untrusted code**. The term "sandbox" is used throughout these docs simply to refer to a separate context, and does not confer any security guarantees. diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 150a1248b146b9..5b531639e77de5 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -6,7 +6,7 @@ Each release line has a staging branch that the releaser will use as a scratch pad while preparing a release. The branch name is formatted as follows: `vN.x-staging` where `N` is the major release number. -*Note*: For the active staging branches see the [Release Schedule][]. +For the active staging branches see the [Release Schedule][]. ## What needs to be backported? diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 4606b1897a7f40..ccc3257c7a90cc 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -228,7 +228,7 @@ to be cherry-picked in the Node.js repository and V8-CI must test the change. * Open a cherry-pick PR on `nodejs/node` targeting the *vY.x-staging* branch and notify the `@nodejs/v8` team. * Run the Node.js [V8 CI] in addition to the [Node.js CI]. - Note: The CI uses the `test-v8` target in the `Makefile`, which uses + The CI uses the `test-v8` target in the `Makefile`, which uses `tools/make-v8.sh` to reconstruct a git tree in the `deps/v8` directory to run V8 tests. diff --git a/doc/guides/maintaining-the-build-files.md b/doc/guides/maintaining-the-build-files.md index f3f7bbf5e2c0fd..2f89362b8ff23f 100644 --- a/doc/guides/maintaining-the-build-files.md +++ b/doc/guides/maintaining-the-build-files.md @@ -11,7 +11,7 @@ There are three main build files that may be directly run when building Node.js: - `configure`: A Python 2 script that detects system capabilities and runs [GYP][]. It generates `config.gypi` which includes parameters used by GYP to create platform-dependent build files. Its output is usually in one of these - formats: Makefile, MSbuild, ninja, or XCode project files. (Note: the main + formats: Makefile, MSbuild, ninja, or XCode project files (the main Makefile mentioned below is maintained separately by humans). For a detailed guide on this script, see [configure](#configure). - `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a diff --git a/doc/guides/using-internal-errors.md b/doc/guides/using-internal-errors.md index d22fc68e0f34c4..77eabb4ad48dec 100644 --- a/doc/guides/using-internal-errors.md +++ b/doc/guides/using-internal-errors.md @@ -14,7 +14,7 @@ in the ecosystem. For that reason, Node.js has considered error message changes to be breaking changes. By providing a permanent identifier for a specific error, we reduce the need for userland code to inspect error messages. -*Note*: Switching an existing error to use the `internal/errors` module must be +Switching an existing error to use the `internal/errors` module must be considered a `semver-major` change. ## Using internal/errors.js diff --git a/doc/node.1 b/doc/node.1 index 4c97240ee716a6..40d661b0bde540 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -227,16 +227,6 @@ and . .It Fl -v8-options Print V8 command-line options. -.Pp -Note: V8 options allow words to be separated by both dashes -.Sy ( - ) -or underscores -.Sy ( _ ) . -.Pp -For example, -.Fl -stack-trace-limit -is equivalent to -.Fl -stack_trace_limit . . .It Fl -v8-pool-size Ns = Ns Ar num Set V8's thread pool size which will be used to allocate background jobs. diff --git a/doc/releases.md b/doc/releases.md index edbe255528ff7c..5781a9d5fd490f 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -182,7 +182,7 @@ and also if there are non-trivial API changes. The rules are not yet strictly defined, so if in doubt, please confer with someone that will have a more informed perspective, such as a member of the NAN team. -*Note*: It is current TSC policy to bump major version when ABI changes. If you +It is current TSC policy to bump major version when ABI changes. If you see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. Commits may need to be reverted or a major version bump may need to happen. @@ -263,7 +263,7 @@ doc/api/*.md`, and substitute this node version with `sed -i "s/REPLACEME/$VERSION/g" doc/api/*.md` or `perl -pi -e "s/REPLACEME/$VERSION/g" doc/api/*.md`. -*Note*: `$VERSION` should be prefixed with a `v`. +`$VERSION` should be prefixed with a `v`. If this release includes any new deprecations it is necessary to ensure that those are assigned a proper static deprecation code. These are listed in the @@ -507,7 +507,7 @@ release, you should re-run `tools/release.sh` after the ARM builds have finished. That will move the ARM artifacts into the correct location. You will be prompted to re-sign SHASUMS256.txt. -*Note*: It is possible to only sign a release by running `./tools/release.sh -s +It is possible to only sign a release by running `./tools/release.sh -s vX.Y.Z`. ### 14. Check the Release