From c8bf42af51f7e3bd653ecac09e91cffbd24f8b21 Mon Sep 17 00:00:00 2001 From: Denys Otrishko Date: Fri, 26 Oct 2018 19:27:40 +0300 Subject: [PATCH] doc: remove notice of dashes in V8 options Previously only V8 options supported both dashes in them (making them equivalent), but now Node.js also supports both styles so the note can be removed. PR-URL: https://github.com/nodejs/node/pull/23903 Refs: https://github.com/nodejs/node/pull/18592 Reviewed-By: Richard Lau Reviewed-By: James M Snell Reviewed-By: Vse Mozhet Byt Reviewed-By: Trivikram Kamat Reviewed-By: George Adams --- doc/STYLE_GUIDE.md | 4 ---- doc/api/assert.md | 12 ++++++------ doc/api/child_process.md | 4 ++-- doc/api/crypto.md | 2 +- doc/api/dgram.md | 2 +- doc/api/domain.md | 2 +- doc/api/path.md | 2 +- doc/api/vm.md | 2 +- doc/guides/backporting-to-release-lines.md | 2 +- doc/guides/maintaining-V8.md | 2 +- doc/guides/maintaining-the-build-files.md | 2 +- doc/guides/using-internal-errors.md | 2 +- doc/node.1 | 10 ---------- doc/releases.md | 6 +++--- 14 files changed, 20 insertions(+), 34 deletions(-) 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