Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: finish cleaning up *Note* tags #23903

Closed
wants to merge 3 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions doc/STYLE_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`. ```
<!--lint disable maximum-line-length remark-lint-->
Expand Down
12 changes: 6 additions & 6 deletions doc/api/assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -426,10 +426,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.
Expand Down Expand Up @@ -472,8 +472,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.

Expand Down
4 changes: 2 additions & 2 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -1056,9 +1056,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';
Expand Down
2 changes: 1 addition & 1 deletion doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -845,7 +845,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(
Expand Down
2 changes: 1 addition & 1 deletion doc/api/dgram.md
Original file line number Diff line number Diff line change
Expand Up @@ -419,7 +419,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.*
Expand Down
2 changes: 1 addition & 1 deletion doc/api/domain.md
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
2 changes: 1 addition & 1 deletion doc/api/path.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/vm.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<!--name=vm-->

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.
Expand Down
2 changes: 1 addition & 1 deletion doc/guides/backporting-to-release-lines.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?

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

Expand Down
2 changes: 1 addition & 1 deletion doc/guides/maintaining-the-build-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/guides/using-internal-errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 0 additions & 10 deletions doc/node.1
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 3 additions & 3 deletions doc/releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down