Skip to content

Commit

Permalink
doc: make the style of notes consistent
Browse files Browse the repository at this point in the history
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

PR-URL: #13133
Fixes: #13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
  • Loading branch information
aqrln authored and jasnell committed May 28, 2017
1 parent d99b7bc commit cd2824c
Show file tree
Hide file tree
Showing 28 changed files with 189 additions and 174 deletions.
4 changes: 4 additions & 0 deletions doc/STYLE_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@
* 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.

[plugin]: http://editorconfig.org/#download
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
4 changes: 2 additions & 2 deletions doc/api/addons.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,13 +113,13 @@ specifically to compile Node.js Addons.
}
```

*Note: A version of the `node-gyp` utility is bundled and distributed with
*Note*: A version of the `node-gyp` utility is bundled and distributed with
Node.js as part of `npm`. This version is not made directly available for
developers to use and is intended only to support the ability to use the
`npm install` command to compile and install Addons. Developers who wish to
use `node-gyp` directly can install it using the command
`npm install -g node-gyp`. See the `node-gyp` [installation instructions][] for
more information, including platform-specific requirements.*
more information, including platform-specific requirements.

Once the `binding.gyp` file has been created, use `node-gyp configure` to
generate the appropriate project build files for the current platform. This
Expand Down
16 changes: 8 additions & 8 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,11 +193,11 @@ The character encodings currently supported by Node.js include:

* `'hex'` - Encode each byte as two hexadecimal characters.

_Note_: Today's browsers follow the [WHATWG spec] which aliases both 'latin1' and
ISO-8859-1 to win-1252. This means that while doing something like `http.get()`,
if the returned charset is one of those listed in the WHATWG spec it's possible
that the server actually returned win-1252-encoded data, and using `'latin1'`
encoding may incorrectly decode the characters.
*Note*: Today's browsers follow the [WHATWG spec] which aliases both 'latin1'
and ISO-8859-1 to win-1252. This means that while doing something like
`http.get()`, if the returned charset is one of those listed in the WHATWG spec
it's possible that the server actually returned win-1252-encoded data, and
using `'latin1'` encoding may incorrectly decode the characters.

## Buffers and TypedArray
<!-- YAML
Expand Down Expand Up @@ -686,7 +686,7 @@ Returns the actual byte length of a string. This is not the same as
[`String.prototype.length`] since that returns the number of *characters* in
a string.

*Note* that for `'base64'` and `'hex'`, this function assumes valid input. For
*Note*: For `'base64'` and `'hex'`, this function assumes valid input. For
strings that contain non-Base64/Hex-encoded data (e.g. whitespace), the return
value might be greater than the length of a `Buffer` created from the string.

Expand Down Expand Up @@ -1868,8 +1868,8 @@ changes:
Returns a new `Buffer` that references the same memory as the original, but
offset and cropped by the `start` and `end` indices.

**Note that modifying the new `Buffer` slice will modify the memory in the
original `Buffer` because the allocated memory of the two objects overlap.**
*Note*: Modifying the new `Buffer` slice will modify the memory in the
original `Buffer` because the allocated memory of the two objects overlap.

Example: Create a `Buffer` with the ASCII alphabet, take a slice, and then modify
one byte from the original `Buffer`
Expand Down
46 changes: 24 additions & 22 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,9 +163,9 @@ exec('echo "The \\$HOME variable is $HOME"');
//The $HOME variable is escaped in the first instance, but not in the second
```

**Note: Never pass unsanitised user input to this function. Any input
*Note*: Never pass unsanitised user input to this function. Any input
containing shell metacharacters may be used to trigger arbitrary command
execution.**
execution.

```js
const exec = require('child_process').exec;
Expand Down Expand Up @@ -211,8 +211,8 @@ If `timeout` is greater than `0`, the parent will send the signal
identified by the `killSignal` property (the default is `'SIGTERM'`) if the
child runs longer than `timeout` milliseconds.

*Note: Unlike the exec(3) POSIX system call, `child_process.exec()` does not
replace the existing process and uses a shell to execute the command.*
*Note*: Unlike the exec(3) POSIX system call, `child_process.exec()` does not
replace the existing process and uses a shell to execute the command.

If this method is invoked as its [`util.promisify()`][]ed version, it returns
a Promise for an object with `stdout` and `stderr` properties.
Expand Down Expand Up @@ -348,8 +348,8 @@ parent process using the file descriptor (fd) identified using the
environment variable `NODE_CHANNEL_FD` on the child process. The input and
output on this fd is expected to be line delimited JSON objects.

*Note: Unlike the fork(2) POSIX system call, `child_process.fork()` does
not clone the current process.*
*Note*: Unlike the fork(2) POSIX system call, `child_process.fork()` does
not clone the current process.

### child_process.spawn(command[, args][, options])
<!-- YAML
Expand Down Expand Up @@ -387,9 +387,9 @@ The `child_process.spawn()` method spawns a new process using the given
`command`, with command line arguments in `args`. If omitted, `args` defaults
to an empty array.

**Note: If the `shell` option is enabled, do not pass unsanitised user input to
*Note*: If the `shell` option is enabled, do not pass unsanitised user input to
this function. Any input containing shell metacharacters may be used to
trigger arbitrary command execution.**
trigger arbitrary command execution.

A third argument may be used to specify additional options, with these defaults:

Expand Down Expand Up @@ -476,13 +476,13 @@ child.on('error', (err) => {
});
```

*Note: Certain platforms (macOS, Linux) will use the value of `argv[0]` for the
process title while others (Windows, SunOS) will use `command`.*
*Note*: Certain platforms (macOS, Linux) will use the value of `argv[0]` for
the process title while others (Windows, SunOS) will use `command`.

*Note: Node.js currently overwrites `argv[0]` with `process.execPath` on
*Note*: Node.js currently overwrites `argv[0]` with `process.execPath` on
startup, so `process.argv[0]` in a Node.js child process will not match the
`argv0` parameter passed to `spawn` from the parent, retrieve it with the
`process.argv0` property instead.*
`process.argv0` property instead.

#### options.detached
<!-- YAML
Expand Down Expand Up @@ -673,9 +673,11 @@ The `child_process.execFileSync()` method is generally identical to
[`child_process.execFile()`][] with the exception that the method will not return
until the child process has fully closed. When a timeout has been encountered
and `killSignal` is sent, the method won't return until the process has
completely exited. *Note that if the child process intercepts and handles
the `SIGTERM` signal and does not exit, the parent process will still wait
until the child process has exited.*
completely exited.

*Note*: If the child process intercepts and handles the `SIGTERM` signal and
does not exit, the parent process will still wait until the child process has
exited.

If the process times out, or has a non-zero exit code, this method ***will***
throw. The [`Error`][] object will contain the entire result from
Expand Down Expand Up @@ -729,9 +731,9 @@ If the process times out, or has a non-zero exit code, this method ***will***
throw. The [`Error`][] object will contain the entire result from
[`child_process.spawnSync()`][]

**Note: Never pass unsanitised user input to this function. Any input
*Note*: Never pass unsanitised user input to this function. Any input
containing shell metacharacters may be used to trigger arbitrary command
execution.**
execution.

### child_process.spawnSync(command[, args][, options])
<!-- YAML
Expand Down Expand Up @@ -789,9 +791,9 @@ completely exited. Note that if the process intercepts and handles the
`SIGTERM` signal and doesn't exit, the parent process will wait until the child
process has exited.

**Note: If the `shell` option is enabled, do not pass unsanitised user input to
this function. Any input containing shell metacharacters may be used to
trigger arbitrary command execution.**
*Note*: If the `shell` option is enabled, do not pass unsanitised user input
to this function. Any input containing shell metacharacters may be used to
trigger arbitrary command execution.

## Class: ChildProcess
<!-- YAML
Expand Down Expand Up @@ -1166,8 +1168,8 @@ tracking when the socket is destroyed. To indicate this, the `.connections`
property becomes `null`. It is recommended not to use `.maxConnections` when
this occurs.

*Note: this function uses [`JSON.stringify()`][] internally to serialize the
`message`.*
*Note*: This function uses [`JSON.stringify()`][] internally to serialize the
`message`.

### child.stderr
<!-- YAML
Expand Down
10 changes: 5 additions & 5 deletions doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -290,8 +290,8 @@ added: v0.1.3

Print v8 command line options.

Note: v8 options allow words to be separated by both dashes (`-`) or underscores
(`_`).
*Note*: V8 options allow words to be separated by both dashes (`-`) or
underscores (`_`).

For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`.

Expand Down Expand Up @@ -394,7 +394,7 @@ added: v0.1.32

`':'`-separated list of directories prefixed to the module search path.

_Note: on Windows, this is a `';'`-separated list instead._
*Note*: On Windows, this is a `';'`-separated list instead.


### `NODE_DISABLE_COLORS=1`
Expand Down Expand Up @@ -525,7 +525,7 @@ added: v7.7.0
If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's directory
containing trusted certificates.

Note: Be aware that unless the child environment is explicitly set, this
*Note*: Be aware that unless the child environment is explicitly set, this
evironment variable will be inherited by any child processes, and if they use
OpenSSL, it may cause them to trust the same CAs as node.

Expand All @@ -537,7 +537,7 @@ added: v7.7.0
If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's file
containing trusted certificates.

Note: Be aware that unless the child environment is explicitly set, this
*Note*: Be aware that unless the child environment is explicitly set, this
evironment variable will be inherited by any child processes, and if they use
OpenSSL, it may cause them to trust the same CAs as node.

Expand Down
8 changes: 4 additions & 4 deletions doc/api/console.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,8 +121,8 @@ console.assert(false, 'Whoops %s', 'didn\'t work');
// AssertionError: Whoops didn't work
```

*Note: the `console.assert()` method is implemented differently in Node.js
than the `console.assert()` method [available in browsers][web-api-assert].*
*Note*: The `console.assert()` method is implemented differently in Node.js
than the `console.assert()` method [available in browsers][web-api-assert].

Specifically, in browsers, calling `console.assert()` with a falsy
assertion will cause the `message` to be printed to the console without
Expand Down Expand Up @@ -282,10 +282,10 @@ console.timeEnd('100-elements');
// prints 100-elements: 225.438ms
```

*Note: As of Node.js v6.0.0, `console.timeEnd()` deletes the timer to avoid
*Note*: As of Node.js v6.0.0, `console.timeEnd()` deletes the timer to avoid
leaking it. On older versions, the timer persisted. This allowed
`console.timeEnd()` to be called multiple times for the same label. This
functionality was unintended and is no longer supported.*
functionality was unintended and is no longer supported.

### console.trace([message][, ...args])
<!-- YAML
Expand Down
2 changes: 1 addition & 1 deletion doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -1820,7 +1820,7 @@ comparing HMAC digests or secret values like authentication cookies or
`a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they
must have the same length.

**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the
*Note*: Use of `crypto.timingSafeEqual` does not guarantee that the
*surrounding* code is timing-safe. Care should be taken to ensure that the
surrounding code does not introduce timing vulnerabilities.

Expand Down
8 changes: 4 additions & 4 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -531,8 +531,8 @@ Type: Documentation-only
The `http` module `ServerResponse.prototype.writeHeader()` API has been
deprecated. Please use `ServerResponse.prototype.writeHead()` instead.

*Note*: The `ServerResponse.prototype.writeHeader()` method was never documented
as an officially supported API.
*Note*: The `ServerResponse.prototype.writeHeader()` method was never
documented as an officially supported API.

<a id="DEP0064"></a>
### DEP0064: tls.createSecurePair()
Expand Down Expand Up @@ -568,8 +568,8 @@ properties have been deprecated. Please instead use one of the public methods
`outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working
with outgoing headers.

*Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were never
documented as officially supported properties.
*Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were
never documented as officially supported properties.

<a id="DEP0067"></a>
### DEP0067: OutgoingMessage.prototype.\_renderHeaders
Expand Down
2 changes: 1 addition & 1 deletion doc/api/domain.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ if (cluster.isMaster) {
d.on('error', (er) => {
console.error(`error ${er.stack}`);

// Note: we're in dangerous territory!
// Note: 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/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ myEmitter.emit('error', new Error('whoops!'));

To guard against crashing the Node.js process, a listener can be registered
on the [`process` object's `uncaughtException` event][] or the [`domain`][] module
can be used. (_Note, however, that the `domain` module has been deprecated_)
can be used. (Note, however, that the `domain` module has been deprecated.)

```js
const myEmitter = new MyEmitter();
Expand Down
30 changes: 16 additions & 14 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ filesystems that allow for non-UTF-8 filenames. For most typical
uses, working with paths as Buffers will be unnecessary, as the string
API converts to and from UTF-8 automatically.

*Note* that on certain file systems (such as NTFS and HFS+) filenames
*Note*: On certain file systems (such as NTFS and HFS+) filenames
will always be encoded as UTF-8. On such file systems, passing
non-UTF-8 encoded Buffers to `fs` functions will not work as expected.

Expand Down Expand Up @@ -1546,8 +1546,8 @@ On Linux, positional writes don't work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.

*Note*: The behavior of `fs.open()` is platform-specific for some flags. As such,
opening a directory on macOS and Linux with the `'a+'` flag - see example
*Note*: The behavior of `fs.open()` is platform-specific for some flags. As
such, opening a directory on macOS and Linux with the `'a+'` flag - see example
below - will return an error. In contrast, on Windows and FreeBSD, a file
descriptor will be returned.

Expand Down Expand Up @@ -2156,9 +2156,9 @@ effectively stopping watching of `filename`.
Calling `fs.unwatchFile()` with a filename that is not being watched is a
no-op, not an error.

*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`.
`fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()`
when possible.
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and
`fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()`
and `fs.unwatchFile()` when possible.

## fs.utimes(path, atime, mtime, callback)
<!-- YAML
Expand All @@ -2185,7 +2185,7 @@ changes:

Change file timestamps of the file referenced by the supplied path.

Note: the arguments `atime` and `mtime` of the following related functions
*Note*: The arguments `atime` and `mtime` of the following related functions
follow these rules:

- The value should be a Unix timestamp in seconds. For example, `Date.now()`
Expand Down Expand Up @@ -2366,11 +2366,12 @@ These stat objects are instances of `fs.Stat`.
To be notified when the file was modified, not just accessed, it is necessary
to compare `curr.mtime` and `prev.mtime`.

*Note*: when an `fs.watchFile` operation results in an `ENOENT` error, it will
invoke the listener once, with all the fields zeroed (or, for dates, the Unix
Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, instead
of zero. If the file is created later on, the listener will be called again,
with the latest stat objects. This is a change in functionality since v0.10.
*Note*: When an `fs.watchFile` operation results in an `ENOENT` error, it
will invoke the listener once, with all the fields zeroed (or, for dates, the
Unix Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`,
instead of zero. If the file is created later on, the listener will be called
again, with the latest stat objects. This is a change in functionality since
v0.10.

*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile` and
`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
Expand Down Expand Up @@ -2577,8 +2578,9 @@ Synchronous versions of [`fs.write()`][]. Returns the number of bytes written.

## FS Constants

The following constants are exported by `fs.constants`. **Note:** Not every
constant will be available on every operating system.
The following constants are exported by `fs.constants`.

*Note*: Not every constant will be available on every operating system.

### File Access Constants

Expand Down
8 changes: 4 additions & 4 deletions doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,8 +268,8 @@ Until the data is consumed, the `'end'` event will not fire. Also, until
the data is read it will consume memory that can eventually lead to a
'process out of memory' error.

Note: Node.js does not check whether Content-Length and the length of the body
which has been transmitted are equal or not.
*Note*: Node.js does not check whether Content-Length and the length of the
body which has been transmitted are equal or not.

The request implements the [Writable Stream][] interface. This is an
[`EventEmitter`][] with the following events:
Expand Down Expand Up @@ -765,7 +765,7 @@ Begin accepting connections on the specified `port` and `hostname`. If the
[unspecified IPv6 address][] (`::`) when IPv6 is available, or the
[unspecified IPv4 address][] (`0.0.0.0`) otherwise.

*Note*: in most operating systems, listening to the
*Note*: In most operating systems, listening to the
[unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
the [unspecified IPv4 address][] (`0.0.0.0`).

Expand Down Expand Up @@ -1177,7 +1177,7 @@ the second parameter specifies how to encode it into a byte stream.
By default the `encoding` is `'utf8'`. `callback` will be called when this chunk
of data is flushed.

**Note**: This is the raw HTTP body and has nothing to do with
*Note*: This is the raw HTTP body and has nothing to do with
higher-level multi-part body encodings that may be used.

The first time [`response.write()`][] is called, it will send the buffered
Expand Down
Loading

0 comments on commit cd2824c

Please sign in to comment.