lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: make the style of notes consistent 

Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

PR-URL: https://github.com/nodejs/node/pull/13133
Fixes: https://github.com/nodejs/node/issues/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>
v6
Alexey Orlenko 8 years ago
committed by Refael Ackermann
parent
b3d1e3d4c7
commit
2af49b6c89
28 changed files with 189 additions and 174 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 4
      doc/STYLE_GUIDE.md
  2. 4
      doc/api/addons.md
  3. 16
      doc/api/buffer.md
  4. 46
      doc/api/child_process.md
  5. 10
      doc/api/cli.md
  6. 8
      doc/api/console.md
  7. 2
      doc/api/crypto.md
  8. 8
      doc/api/deprecations.md
  9. 2
      doc/api/domain.md
  10. 2
      doc/api/events.md
  11. 30
      doc/api/fs.md
  12. 8
      doc/api/http.md
  13. 19
      doc/api/modules.md
  14. 10
      doc/api/n-api.md
  15. 7
      doc/api/net.md
  16. 13
      doc/api/os.md
  17. 78
      doc/api/process.md
  18. 2
      doc/api/readline.md
  19. 20
      doc/api/stream.md
  20. 45
      doc/api/tls.md
  21. 6
      doc/api/util.md
  22. 8
      doc/api/zlib.md
  23. 2
      doc/changelogs/CHANGELOG_V010.md
  24. 2
      doc/changelogs/CHANGELOG_V012.md
  25. 2
      doc/changelogs/CHANGELOG_V4.md
  26. 2
      doc/changelogs/CHANGELOG_V5.md
  27. 2
      doc/changelogs/CHANGELOG_V6.md
  28. 5
      doc/releases.md

4
doc/STYLE_GUIDE.md
View File

@ -61,6 +61,10 @@
* References to constructor instances should use camelCase. * References to constructor instances should use camelCase.
* References to methods should be used with parentheses: for example, * References to methods should be used with parentheses: for example,
`socket.end()` instead of `socket.end`. `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 [plugin]: http://editorconfig.org/#download
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma [Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma

4
doc/api/addons.md
View File

@ -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 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 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 `npm install` command to compile and install Addons. Developers who wish to
use `node-gyp` directly can install it using the command use `node-gyp` directly can install it using the command
`npm install -g node-gyp`. See the `node-gyp` [installation instructions][] for `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 Once the `binding.gyp` file has been created, use `node-gyp configure` to
generate the appropriate project build files for the current platform. This generate the appropriate project build files for the current platform. This

16
doc/api/buffer.md
View File

@ -193,11 +193,11 @@ The character encodings currently supported by Node.js include:
* `'hex'` - Encode each byte as two hexadecimal characters. * `'hex'` - Encode each byte as two hexadecimal characters.
_Note_: Today's browsers follow the [WHATWG spec] which aliases both 'latin1' and *Note*: Today's browsers follow the [WHATWG spec] which aliases both 'latin1'
ISO-8859-1 to win-1252. This means that while doing something like `http.get()`, and ISO-8859-1 to win-1252. This means that while doing something like
if the returned charset is one of those listed in the WHATWG spec it's possible `http.get()`, if the returned charset is one of those listed in the WHATWG spec
that the server actually returned win-1252-encoded data, and using `'latin1'` it's possible that the server actually returned win-1252-encoded data, and
encoding may incorrectly decode the characters. using `'latin1'` encoding may incorrectly decode the characters.
## Buffers and TypedArray ## Buffers and TypedArray
<!-- YAML <!-- YAML
@ -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 [`String.prototype.length`] since that returns the number of *characters* in
a string. 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 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. value might be greater than the length of a `Buffer` created from the string.
@ -1868,8 +1868,8 @@ changes:
Returns a new `Buffer` that references the same memory as the original, but Returns a new `Buffer` that references the same memory as the original, but
offset and cropped by the `start` and `end` indices. offset and cropped by the `start` and `end` indices.
**Note that modifying the new `Buffer` slice will modify the memory in the *Note*: Modifying the new `Buffer` slice will modify the memory in the
original `Buffer` because the allocated memory of the two objects overlap.** 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 Example: Create a `Buffer` with the ASCII alphabet, take a slice, and then modify
one byte from the original `Buffer` one byte from the original `Buffer`

46
doc/api/child_process.md
View File

@ -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 //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 containing shell metacharacters may be used to trigger arbitrary command
execution.** execution.
```js ```js
const exec = require('child_process').exec; const exec = require('child_process').exec;
@ -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 identified by the `killSignal` property (the default is `'SIGTERM'`) if the
child runs longer than `timeout` milliseconds. child runs longer than `timeout` milliseconds.
*Note: Unlike the exec(3) POSIX system call, `child_process.exec()` does not *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.* 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 If this method is invoked as its [`util.promisify()`][]ed version, it returns
a Promise for an object with `stdout` and `stderr` properties. a Promise for an object with `stdout` and `stderr` properties.
@ -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 environment variable `NODE_CHANNEL_FD` on the child process. The input and
output on this fd is expected to be line delimited JSON objects. output on this fd is expected to be line delimited JSON objects.
*Note: Unlike the fork(2) POSIX system call, `child_process.fork()` does *Note*: Unlike the fork(2) POSIX system call, `child_process.fork()` does
not clone the current process.* not clone the current process.
### child_process.spawn(command[, args][, options]) ### child_process.spawn(command[, args][, options])
<!-- YAML <!-- YAML
@ -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 `command`, with command line arguments in `args`. If omitted, `args` defaults
to an empty array. 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 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: A third argument may be used to specify additional options, with these defaults:
@ -476,13 +476,13 @@ child.on('error', (err) => {
}); });
``` ```
*Note: Certain platforms (macOS, Linux) will use the value of `argv[0]` for the *Note*: Certain platforms (macOS, Linux) will use the value of `argv[0]` for
process title while others (Windows, SunOS) will use `command`.* 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 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 `argv0` parameter passed to `spawn` from the parent, retrieve it with the
`process.argv0` property instead.* `process.argv0` property instead.
#### options.detached #### options.detached
<!-- YAML <!-- YAML
@ -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 [`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 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 and `killSignal` is sent, the method won't return until the process has
completely exited. *Note that if the child process intercepts and handles completely exited.
the `SIGTERM` signal and does not exit, the parent process will still wait
until the child process has 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*** 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 throw. The [`Error`][] object will contain the entire result from
@ -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 throw. The [`Error`][] object will contain the entire result from
[`child_process.spawnSync()`][] [`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 containing shell metacharacters may be used to trigger arbitrary command
execution.** execution.
### child_process.spawnSync(command[, args][, options]) ### child_process.spawnSync(command[, args][, options])
<!-- YAML <!-- YAML
@ -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 `SIGTERM` signal and doesn't exit, the parent process will wait until the child
process has exited. process has exited.
**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
this function. Any input containing shell metacharacters may be used to to this function. Any input containing shell metacharacters may be used to
trigger arbitrary command execution.** trigger arbitrary command execution.
## Class: ChildProcess ## Class: ChildProcess
<!-- YAML <!-- YAML
@ -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 property becomes `null`. It is recommended not to use `.maxConnections` when
this occurs. this occurs.
*Note: this function uses [`JSON.stringify()`][] internally to serialize the *Note*: This function uses [`JSON.stringify()`][] internally to serialize the
`message`.* `message`.
### child.stderr ### child.stderr
<!-- YAML <!-- YAML

10
doc/api/cli.md
View File

@ -290,8 +290,8 @@ added: v0.1.3
Print v8 command line options. 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`. For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`.
@ -394,7 +394,7 @@ added: v0.1.32
`':'`-separated list of directories prefixed to the module search path. `':'`-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` ### `NODE_DISABLE_COLORS=1`
@ -525,7 +525,7 @@ added: v7.7.0
If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's directory If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's directory
containing trusted certificates. 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 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. OpenSSL, it may cause them to trust the same CAs as node.
@ -537,7 +537,7 @@ added: v7.7.0
If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's file If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's file
containing trusted certificates. 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 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. OpenSSL, it may cause them to trust the same CAs as node.

8
doc/api/console.md
View File

@ -121,8 +121,8 @@ console.assert(false, 'Whoops %s', 'didn\'t work');
// AssertionError: Whoops didn't work // AssertionError: Whoops didn't work
``` ```
*Note: the `console.assert()` method is implemented differently in Node.js *Note*: The `console.assert()` method is implemented differently in Node.js
than the `console.assert()` method [available in browsers][web-api-assert].* than the `console.assert()` method [available in browsers][web-api-assert].
Specifically, in browsers, calling `console.assert()` with a falsy Specifically, in browsers, calling `console.assert()` with a falsy
assertion will cause the `message` to be printed to the console without assertion will cause the `message` to be printed to the console without
@ -282,10 +282,10 @@ console.timeEnd('100-elements');
// prints 100-elements: 225.438ms // 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 leaking it. On older versions, the timer persisted. This allowed
`console.timeEnd()` to be called multiple times for the same label. This `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]) ### console.trace([message][, ...args])
<!-- YAML <!-- YAML

2
doc/api/crypto.md
View File

@ -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 `a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they
must have the same length. 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 is timing-safe. Care should be taken to ensure that the
surrounding code does not introduce timing vulnerabilities. surrounding code does not introduce timing vulnerabilities.

8
doc/api/deprecations.md
View File

@ -531,8 +531,8 @@ Type: Documentation-only
The `http` module `ServerResponse.prototype.writeHeader()` API has been The `http` module `ServerResponse.prototype.writeHeader()` API has been
deprecated. Please use `ServerResponse.prototype.writeHead()` instead. deprecated. Please use `ServerResponse.prototype.writeHead()` instead.
*Note*: The `ServerResponse.prototype.writeHeader()` method was never documented *Note*: The `ServerResponse.prototype.writeHeader()` method was never
as an officially supported API. documented as an officially supported API.
<a id="DEP0064"></a> <a id="DEP0064"></a>
### DEP0064: tls.createSecurePair() ### DEP0064: tls.createSecurePair()
@ -568,8 +568,8 @@ properties have been deprecated. Please instead use one of the public methods
`outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working `outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working
with outgoing headers. with outgoing headers.
*Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were never *Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were
documented as officially supported properties. never documented as officially supported properties.
<a id="DEP0067"></a> <a id="DEP0067"></a>
### DEP0067: OutgoingMessage.prototype.\_renderHeaders ### DEP0067: OutgoingMessage.prototype.\_renderHeaders

2
doc/api/domain.md
View File

@ -115,7 +115,7 @@ if (cluster.isMaster) {
d.on('error', (er) => { d.on('error', (er) => {
console.error(`error ${er.stack}`); console.error(`error ${er.stack}`);
// Note: we're in dangerous territory! // Note: We're in dangerous territory!
// By definition, something unexpected occurred, // By definition, something unexpected occurred,
// which we probably didn't want. // which we probably didn't want.
// Anything can happen now! Be very careful! // Anything can happen now! Be very careful!

2
doc/api/events.md
View File

@ -142,7 +142,7 @@ myEmitter.emit('error', new Error('whoops!'));
To guard against crashing the Node.js process, a listener can be registered To guard against crashing the Node.js process, a listener can be registered
on the [`process` object's `uncaughtException` event][] or the [`domain`][] module 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 ```js
const myEmitter = new MyEmitter(); const myEmitter = new MyEmitter();

30
doc/api/fs.md
View File

@ -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 uses, working with paths as Buffers will be unnecessary, as the string
API converts to and from UTF-8 automatically. 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 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. non-UTF-8 encoded Buffers to `fs` functions will not work as expected.
@ -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 kernel ignores the position argument and always appends the data to
the end of the file. the end of the file.
*Note*: The behavior of `fs.open()` is platform-specific for some flags. As such, *Note*: The behavior of `fs.open()` is platform-specific for some flags. As
opening a directory on macOS and Linux with the `'a+'` flag - see example 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 below - will return an error. In contrast, on Windows and FreeBSD, a file
descriptor will be returned. descriptor will be returned.
@ -2156,9 +2156,9 @@ effectively stopping watching of `filename`.
Calling `fs.unwatchFile()` with a filename that is not being watched is a Calling `fs.unwatchFile()` with a filename that is not being watched is a
no-op, not an error. no-op, not an error.
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`. *Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and
`fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()` `fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()`
when possible. and `fs.unwatchFile()` when possible.
## fs.utimes(path, atime, mtime, callback) ## fs.utimes(path, atime, mtime, callback)
<!-- YAML <!-- YAML
@ -2185,7 +2185,7 @@ changes:
Change file timestamps of the file referenced by the supplied path. 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: follow these rules:
- The value should be a Unix timestamp in seconds. For example, `Date.now()` - The value should be a Unix timestamp in seconds. For example, `Date.now()`
@ -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 be notified when the file was modified, not just accessed, it is necessary
to compare `curr.mtime` and `prev.mtime`. to compare `curr.mtime` and `prev.mtime`.
*Note*: when an `fs.watchFile` operation results in an `ENOENT` error, it will *Note*: When an `fs.watchFile` operation results in an `ENOENT` error, it
invoke the listener once, with all the fields zeroed (or, for dates, the Unix will invoke the listener once, with all the fields zeroed (or, for dates, the
Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, instead Unix Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`,
of zero. If the file is created later on, the listener will be called again, instead of zero. If the file is created later on, the listener will be called
with the latest stat objects. This is a change in functionality since v0.10. 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 *Note*: [`fs.watch()`][] is more efficient than `fs.watchFile` and
`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
@ -2577,8 +2578,9 @@ Synchronous versions of [`fs.write()`][]. Returns the number of bytes written.
## FS Constants ## FS Constants
The following constants are exported by `fs.constants`. **Note:** Not every The following constants are exported by `fs.constants`.
constant will be available on every operating system.
*Note*: Not every constant will be available on every operating system.
### File Access Constants ### File Access Constants

8
doc/api/http.md
View File

@ -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 the data is read it will consume memory that can eventually lead to a
'process out of memory' error. 'process out of memory' error.
Note: Node.js does not check whether Content-Length and the length of the body *Note*: Node.js does not check whether Content-Length and the length of the
which has been transmitted are equal or not. body which has been transmitted are equal or not.
The request implements the [Writable Stream][] interface. This is an The request implements the [Writable Stream][] interface. This is an
[`EventEmitter`][] with the following events: [`EventEmitter`][] with the following events:
@ -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 IPv6 address][] (`::`) when IPv6 is available, or the
[unspecified IPv4 address][] (`0.0.0.0`) otherwise. [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 [unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
the [unspecified IPv4 address][] (`0.0.0.0`). the [unspecified IPv4 address][] (`0.0.0.0`).
@ -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 By default the `encoding` is `'utf8'`. `callback` will be called when this chunk
of data is flushed. 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. higher-level multi-part body encodings that may be used.
The first time [`response.write()`][] is called, it will send the buffered The first time [`response.write()`][] is called, it will send the buffered

19
doc/api/modules.md
View File

@ -348,9 +348,9 @@ If this was in a folder at `./some-library`, then
This is the extent of Node.js's awareness of package.json files. This is the extent of Node.js's awareness of package.json files.
Note: If the file specified by the `"main"` entry of `package.json` is missing *Note*: If the file specified by the `"main"` entry of `package.json` is
and can not be resolved, Node.js will report the entire module as missing with missing and can not be resolved, Node.js will report the entire module as
the default error: missing with the default error:
```txt ```txt
Error: Cannot find module 'some-library' Error: Cannot find module 'some-library'
@ -401,8 +401,9 @@ same module resolution semantics.
If the `NODE_PATH` environment variable is set to a colon-delimited list If the `NODE_PATH` environment variable is set to a colon-delimited list
of absolute paths, then Node.js will search those paths for modules if they of absolute paths, then Node.js will search those paths for modules if they
are not found elsewhere. (Note: On Windows, `NODE_PATH` is delimited by are not found elsewhere.
semicolons instead of colons.)
*Note*: On Windows, `NODE_PATH` is delimited by semicolons instead of colons.
`NODE_PATH` was originally created to support loading modules from `NODE_PATH` was originally created to support loading modules from
varying paths before the current [module resolution][] algorithm was frozen. varying paths before the current [module resolution][] algorithm was frozen.
@ -627,10 +628,10 @@ added: v0.5.1
The `module.require` method provides a way to load a module as if The `module.require` method provides a way to load a module as if
`require()` was called from the original module. `require()` was called from the original module.
*Note*: In order to do this, it is necessary to get a reference to the `module` *Note*: In order to do this, it is necessary to get a reference to the
object. Since `require()` returns the `module.exports`, and the `module` is `module` object. Since `require()` returns the `module.exports`, and the
typically *only* available within a specific module's code, it must be `module` is typically *only* available within a specific module's code, it must
explicitly exported in order to be used. be explicitly exported in order to be used.
[`Error`]: errors.html#errors_class_error [`Error`]: errors.html#errors_class_error
[module resolution]: #modules_all_together [module resolution]: #modules_all_together

10
doc/api/n-api.md
View File

@ -241,7 +241,7 @@ typedef struct napi_extended_error_info {
[`napi_get_last_error_info`][] returns the information for the last [`napi_get_last_error_info`][] returns the information for the last
N-API call that was made. N-API call that was made.
**Note:** Do not rely on the content or format of any of the extended *Note*: Do not rely on the content or format of any of the extended
information as it is not subject to SemVer and may change at any time. information as it is not subject to SemVer and may change at any time.
It is intended only for logging purposes. It is intended only for logging purposes.
@ -263,7 +263,7 @@ Returns `napi_ok` if the API succeeded.
This API retrieves a `napi_extended_error_info` structure with information This API retrieves a `napi_extended_error_info` structure with information
about the last error that occured. about the last error that occured.
**Note:** Do not rely on the content or format of any of the extended *Note*: Do not rely on the content or format of any of the extended
information as it is not subject to SemVer and may change at any time. information as it is not subject to SemVer and may change at any time.
It is intended only for logging purposes. It is intended only for logging purposes.
@ -1138,7 +1138,7 @@ This API allocates a `node::Buffer` object and initializes it with data
backed by the passed in buffer. While this is still a fully-supported data backed by the passed in buffer. While this is still a fully-supported data
structure, in most cases using a TypedArray will suffice. structure, in most cases using a TypedArray will suffice.
**Note:** For Node.js >=4 `Buffers` are Uint8Arrays. *Note*: For Node.js >=4 `Buffers` are Uint8Arrays.
#### *napi_create_function* #### *napi_create_function*
<!-- YAML <!-- YAML
@ -2497,7 +2497,7 @@ This API allows an add-on author to create a function object in native code.
This is the primary mechanism to allow calling *into* the add-on's native code This is the primary mechanism to allow calling *into* the add-on's native code
*from* Javascript. *from* Javascript.
**Note:** The newly created function is not automatically visible from *Note*: The newly created function is not automatically visible from
script after this call. Instead, a property must be explicitly set on any script after this call. Instead, a property must be explicitly set on any
object that is visible to JavaScript, in order for the function to be accessible object that is visible to JavaScript, in order for the function to be accessible
from script. from script.
@ -2530,7 +2530,7 @@ const myaddon = require('./addon');
myaddon.sayHello(); myaddon.sayHello();
``` ```
**Note:** The string passed to require is not necessarily the name passed into *Note*: The string passed to require is not necessarily the name passed into
`NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp` `NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp`
responsible for creating the `.node` file. responsible for creating the `.node` file.

7
doc/api/net.md
View File

@ -185,10 +185,11 @@ by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn`
on Linux. The default value of this parameter is 511 (not 512). on Linux. The default value of this parameter is 511 (not 512).
Note: *Note*:
* All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for * All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for
details). details).
* The `server.listen()` method may be called multiple times. Each * The `server.listen()` method may be called multiple times. Each
subsequent call will *re-open* the server using the provided options. subsequent call will *re-open* the server using the provided options.
@ -294,7 +295,7 @@ If `host` is omitted, the server will accept connections on the
[unspecified IPv6 address][] (`::`) when IPv6 is available, or the [unspecified IPv6 address][] (`::`) when IPv6 is available, or the
[unspecified IPv4 address][] (`0.0.0.0`) otherwise. [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 [unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
the [unspecified IPv4 address][] (`0.0.0.0`). the [unspecified IPv4 address][] (`0.0.0.0`).
@ -852,7 +853,7 @@ Possible signatures:
* [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`] * [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`]
for TCP connections. for TCP connections.
*Note*: the [`net.connect()`][] function is an alias to this function. *Note*: The [`net.connect()`][] function is an alias to this function.
### net.createConnection(options[, connectListener]) ### net.createConnection(options[, connectListener])
<!-- YAML <!-- YAML

13
doc/api/os.md
View File

@ -165,8 +165,8 @@ For example:
] ]
``` ```
*Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values of *Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values
all processors are always 0. of all processors are always 0.
## os.endianness() ## os.endianness()
<!-- YAML <!-- YAML
@ -328,8 +328,8 @@ added: v0.3.3
The `os.release()` method returns a string identifying the operating system The `os.release()` method returns a string identifying the operating system
release. release.
*Note*: On POSIX systems, the operating system release is determined by calling *Note*: On POSIX systems, the operating system release is determined by
uname(3). On Windows, `GetVersionExW()` is used. Please see calling uname(3). On Windows, `GetVersionExW()` is used. Please see
https://en.wikipedia.org/wiki/Uname#Examples for more information. https://en.wikipedia.org/wiki/Uname#Examples for more information.
## os.tmpdir() ## os.tmpdir()
@ -406,8 +406,9 @@ operating system response.
## OS Constants ## OS Constants
The following constants are exported by `os.constants`. **Note:** Not all The following constants are exported by `os.constants`.
constants will be available on every operating system.
*Note*: Not all constants will be available on every operating system.
### Signal Constants ### Signal Constants
<!-- YAML <!-- YAML

78
doc/api/process.md
View File

@ -1005,7 +1005,7 @@ if (process.getegid) {
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows *Note*: This function is only available on POSIX platforms (i.e. not Windows
or Android) or Android).
## process.geteuid() ## process.geteuid()
<!-- YAML <!-- YAML
@ -1023,8 +1023,8 @@ if (process.geteuid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.getgid() ## process.getgid()
<!-- YAML <!-- YAML
@ -1042,8 +1042,8 @@ if (process.getgid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.getgroups() ## process.getgroups()
@ -1057,8 +1057,8 @@ The `process.getgroups()` method returns an array with the supplementary group
IDs. POSIX leaves it unspecified if the effective group ID is included but IDs. POSIX leaves it unspecified if the effective group ID is included but
Node.js ensures it always is. Node.js ensures it always is.
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.getuid() ## process.getuid()
<!-- YAML <!-- YAML
@ -1076,8 +1076,8 @@ if (process.getuid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.hrtime([time]) ## process.hrtime([time])
<!-- YAML <!-- YAML
@ -1139,8 +1139,8 @@ process.setgid(1000); // drop root gid
console.log(process.getgroups()); // [ 27, 30, 46, 1000 ] console.log(process.getgroups()); // [ 27, 30, 46, 1000 ]
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.kill(pid[, signal]) ## process.kill(pid[, signal])
<!-- YAML <!-- YAML
@ -1162,9 +1162,9 @@ case, a signal of `0` can be used to test for the existence of a process.
Windows platforms will throw an error if the `pid` is used to kill a process Windows platforms will throw an error if the `pid` is used to kill a process
group. group.
*Note*:Even though the name of this function is `process.kill()`, it is really *Note*: Even though the name of this function is `process.kill()`, it is
just a signal sender, like the `kill` system call. The signal sent may do really just a signal sender, like the `kill` system call. The signal sent may
something other than kill the target process. do something other than kill the target process.
For example: For example:
@ -1181,8 +1181,8 @@ setTimeout(() => {
process.kill(process.pid, 'SIGHUP'); process.kill(process.pid, 'SIGHUP');
``` ```
*Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start the *Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start
debugger, see [Signal Events][]. the debugger, see [Signal Events][].
## process.mainModule ## process.mainModule
<!-- YAML <!-- YAML
@ -1331,7 +1331,7 @@ function definitelyAsync(arg, cb) {
} }
``` ```
*Note*: the next tick queue is completely drained on each pass of the *Note*: The next tick queue is completely drained on each pass of the
event loop **before** additional I/O is processed. As a result, event loop **before** additional I/O is processed. As a result,
recursively setting nextTick callbacks will block any I/O from recursively setting nextTick callbacks will block any I/O from
happening, just like a `while(true);` loop. happening, just like a `while(true);` loop.
@ -1430,7 +1430,7 @@ If Node.js was not spawned with an IPC channel, `process.send()` will be
`undefined`. `undefined`.
*Note*: This function uses [`JSON.stringify()`][] internally to serialize the *Note*: This function uses [`JSON.stringify()`][] internally to serialize the
`message`.* `message`.
## process.setegid(id) ## process.setegid(id)
<!-- YAML <!-- YAML
@ -1456,8 +1456,8 @@ if (process.getegid && process.setegid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.seteuid(id) ## process.seteuid(id)
@ -1484,8 +1484,8 @@ if (process.geteuid && process.seteuid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.setgid(id) ## process.setgid(id)
<!-- YAML <!-- YAML
@ -1511,8 +1511,8 @@ if (process.getgid && process.setgid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.setgroups(groups) ## process.setgroups(groups)
<!-- YAML <!-- YAML
@ -1527,8 +1527,8 @@ to have `root` or the `CAP_SETGID` capability.
The `groups` array can contain numeric group IDs, group names or both. The `groups` array can contain numeric group IDs, group names or both.
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.setuid(id) ## process.setuid(id)
<!-- YAML <!-- YAML
@ -1552,8 +1552,8 @@ if (process.getuid && process.setuid) {
} }
``` ```
*Note*: This function is only available on POSIX platforms (i.e. not Windows or *Note*: This function is only available on POSIX platforms (i.e. not Windows
Android) or Android).
## process.stderr ## process.stderr
@ -1565,7 +1565,7 @@ The `process.stderr` property returns a stream connected to
stream) unless fd `2` refers to a file, in which case it is stream) unless fd `2` refers to a file, in which case it is
a [Writable][] stream. a [Writable][] stream.
Note: `process.stderr` differs from other Node.js streams in important ways, *Note*: `process.stderr` differs from other Node.js streams in important ways,
see [note on process I/O][] for more information. see [note on process I/O][] for more information.
## process.stdin ## process.stdin
@ -1617,7 +1617,7 @@ For example, to copy process.stdin to process.stdout:
process.stdin.pipe(process.stdout); process.stdin.pipe(process.stdout);
``` ```
Note: `process.stdout` differs from other Node.js streams in important ways, *Note*: `process.stdout` differs from other Node.js streams in important ways,
see [note on process I/O][] for more information. see [note on process I/O][] for more information.
### A note on process I/O ### A note on process I/O
@ -1680,14 +1680,14 @@ The `process.title` property returns the current process title (i.e. returns
the current value of `ps`). Assigning a new value to `process.title` modifies the current value of `ps`). Assigning a new value to `process.title` modifies
the current value of `ps`. the current value of `ps`.
*Note*: When a new value is assigned, different platforms will impose different *Note*: When a new value is assigned, different platforms will impose
maximum length restrictions on the title. Usually such restrictions are quite different maximum length restrictions on the title. Usually such restrictions
limited. For instance, on Linux and macOS, `process.title` is limited to the are quite limited. For instance, on Linux and macOS, `process.title` is limited
size of the binary name plus the length of the command line arguments because to the size of the binary name plus the length of the command line arguments
setting the `process.title` overwrites the `argv` memory of the process. because setting the `process.title` overwrites the `argv` memory of the
Node.js v0.8 allowed for longer process title strings by also overwriting the process. Node.js v0.8 allowed for longer process title strings by also
`environ` memory but that was potentially insecure and confusing in some overwriting the `environ` memory but that was potentially insecure and
(rather obscure) cases. confusing in some (rather obscure) cases.
## process.umask([mask]) ## process.umask([mask])
<!-- YAML <!-- YAML
@ -1720,7 +1720,7 @@ added: v0.5.0
The `process.uptime()` method returns the number of seconds the current Node.js The `process.uptime()` method returns the number of seconds the current Node.js
process has been running. process has been running.
*Note*: the return value includes fractions of a second. Use `Math.floor()` *Note*: The return value includes fractions of a second. Use `Math.floor()`
to get whole seconds. to get whole seconds.
## process.version ## process.version

2
doc/api/readline.md
View File

@ -27,7 +27,7 @@ rl.question('What do you think of Node.js? ', (answer) => {
}); });
``` ```
*Note* Once this code is invoked, the Node.js application will not *Note*: Once this code is invoked, the Node.js application will not
terminate until the `readline.Interface` is closed because the interface terminate until the `readline.Interface` is closed because the interface
waits for data to be received on the `input` stream. waits for data to be received on the `input` stream.

20
doc/api/stream.md
View File

@ -893,7 +893,7 @@ A Readable stream in object mode will always return a single item from
a call to [`readable.read(size)`][stream-read], regardless of the value of the a call to [`readable.read(size)`][stream-read], regardless of the value of the
`size` argument. `size` argument.
*Note:* If the `readable.read()` method returns a chunk of data, a `'data'` *Note*: If the `readable.read()` method returns a chunk of data, a `'data'`
event will also be emitted. event will also be emitted.
*Note*: Calling [`stream.read([size])`][stream-read] after the [`'end'`][] *Note*: Calling [`stream.read([size])`][stream-read] after the [`'end'`][]
@ -1346,7 +1346,7 @@ resource.
*Note*: [Transform][] streams provide their own implementation of the *Note*: [Transform][] streams provide their own implementation of the
[`writable._write()`][stream-_write]. [`writable._write()`][stream-_write].
*Note*: **This function MUST NOT be called by application code directly.** It *Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called only by the internal Writable should be implemented by child classes, and called only by the internal Writable
class methods only. class methods only.
@ -1381,7 +1381,7 @@ user programs.
* `callback` {Function} A callback function (optionally with an error * `callback` {Function} A callback function (optionally with an error
argument) to be invoked when processing is complete for the supplied chunks. argument) to be invoked when processing is complete for the supplied chunks.
*Note*: **This function MUST NOT be called by application code directly.** It *Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called only by the internal Writable should be implemented by child classes, and called only by the internal Writable
class methods only. class methods only.
@ -1536,7 +1536,7 @@ const myReadable = new Readable({
* `size` {number} Number of bytes to read asynchronously * `size` {number} Number of bytes to read asynchronously
*Note*: **This function MUST NOT be called by application code directly.** It *Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called only by the internal Readable should be implemented by child classes, and called only by the internal Readable
class methods only. class methods only.
@ -1684,10 +1684,10 @@ Because JavaScript does not have support for multiple inheritance, the
`stream.Duplex` class is extended to implement a [Duplex][] stream (as opposed `stream.Duplex` class is extended to implement a [Duplex][] stream (as opposed
to extending the `stream.Readable` *and* `stream.Writable` classes). to extending the `stream.Readable` *and* `stream.Writable` classes).
*Note*: The `stream.Duplex` class prototypically inherits from `stream.Readable` *Note*: The `stream.Duplex` class prototypically inherits from
and parasitically from `stream.Writable`, but `instanceof` will work properly `stream.Readable` and parasitically from `stream.Writable`, but `instanceof`
for both base classes due to overriding [`Symbol.hasInstance`][] will work properly for both base classes due to overriding
on `stream.Writable`. [`Symbol.hasInstance`][] on `stream.Writable`.
Custom Duplex streams *must* call the `new stream.Duplex([options])` Custom Duplex streams *must* call the `new stream.Duplex([options])`
constructor and implement *both* the `readable._read()` and constructor and implement *both* the `readable._read()` and
@ -1916,7 +1916,7 @@ after all data has been output, which occurs after the callback in
* `callback` {Function} A callback function (optionally with an error * `callback` {Function} A callback function (optionally with an error
argument and data) to be called when remaining data has been flushed. argument and data) to be called when remaining data has been flushed.
*Note*: **This function MUST NOT be called by application code directly.** It *Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called only by the internal Readable should be implemented by child classes, and called only by the internal Readable
class methods only. class methods only.
@ -1951,7 +1951,7 @@ user programs.
argument and data) to be called after the supplied `chunk` has been argument and data) to be called after the supplied `chunk` has been
processed. processed.
*Note*: **This function MUST NOT be called by application code directly.** It *Note*: This function MUST NOT be called by application code directly. It
should be implemented by child classes, and called only by the internal Readable should be implemented by child classes, and called only by the internal Readable
class methods only. class methods only.

45
doc/api/tls.md
View File

@ -488,11 +488,9 @@ changes:
* `secureContext`: Optional TLS context object created with * `secureContext`: Optional TLS context object created with
[`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one
will be created by passing the entire `options` object to will be created by passing the entire `options` object to
`tls.createSecureContext()`. *Note*: In effect, all `tls.createSecureContext()`.
[`tls.createSecureContext()`][] options can be provided, but they will be * ...: Optional [`tls.createSecureContext()`][] options that are used if the
_completely ignored_ unless the `secureContext` option is missing. `secureContext` option is missing, otherwise they are ignored.
* ...: Optional [`tls.createSecureContext()`][] options can be provided, see
the `secureContext` option for more information.
Construct a new `tls.TLSSocket` object from an existing TCP socket. Construct a new `tls.TLSSocket` object from an existing TCP socket.
@ -667,8 +665,8 @@ added: v0.11.4
Returns the TLS session ticket or `undefined` if no session was negotiated. Returns the TLS session ticket or `undefined` if no session was negotiated.
*Note*: This only works with client TLS sockets. Useful only for debugging, for *Note*: This only works with client TLS sockets. Useful only for debugging,
session reuse provide `session` option to [`tls.connect()`][]. for session reuse provide `session` option to [`tls.connect()`][].
### tlsSocket.localAddress ### tlsSocket.localAddress
<!-- YAML <!-- YAML
@ -809,12 +807,10 @@ changes:
* `secureContext`: Optional TLS context object created with * `secureContext`: Optional TLS context object created with
[`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one
will be created by passing the entire `options` object to will be created by passing the entire `options` object to
`tls.createSecureContext()`. *Note*: In effect, all `tls.createSecureContext()`.
[`tls.createSecureContext()`][] options can be provided, but they will be
_completely ignored_ unless the `secureContext` option is missing.
* `lookup`: {Function} Custom lookup function. Defaults to [`dns.lookup()`][]. * `lookup`: {Function} Custom lookup function. Defaults to [`dns.lookup()`][].
* ...: Optional [`tls.createSecureContext()`][] options can be provided, see * ...: Optional [`tls.createSecureContext()`][] options that are used if the
the `secureContext` option for more information. `secureContext` option is missing, otherwise they are ignored.
* `callback` {Function} * `callback` {Function}
The `callback` function, if specified, will be added as a listener for the The `callback` function, if specified, will be added as a listener for the
@ -905,8 +901,8 @@ added: v0.11.3
Same as [`tls.connect()`][] except that `port` and `host` can be provided Same as [`tls.connect()`][] except that `port` and `host` can be provided
as arguments instead of options. as arguments instead of options.
*Note*: A port or host option, if specified, will take precedence over any port *Note*: A port or host option, if specified, will take precedence over any
or host argument. port or host argument.
## tls.createSecureContext(options) ## tls.createSecureContext(options)
@ -971,8 +967,6 @@ changes:
preferences instead of the client's. When `true`, causes preferences instead of the client's. When `true`, causes
`SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see `SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see
[OpenSSL Options][] for more information. [OpenSSL Options][] for more information.
*Note*: [`tls.createServer()`][] sets the default value to `true`, other
APIs that create secure contexts leave it unset.
* `ecdhCurve` {string} A string describing a named curve to use for ECDH key * `ecdhCurve` {string} A string describing a named curve to use for ECDH key
agreement or `false` to disable ECDH. Defaults to agreement or `false` to disable ECDH. Defaults to
[`tls.DEFAULT_ECDH_CURVE`]. Use [`crypto.getCurves()`][] to obtain a list [`tls.DEFAULT_ECDH_CURVE`]. Use [`crypto.getCurves()`][] to obtain a list
@ -994,9 +988,16 @@ changes:
[OpenSSL Options][]. [OpenSSL Options][].
* `sessionIdContext` {string} Optional opaque identifier used by servers to * `sessionIdContext` {string} Optional opaque identifier used by servers to
ensure session state is not shared between applications. Unused by clients. ensure session state is not shared between applications. Unused by clients.
*Note*: [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value
generated from `process.argv`, other APIs that create secure contexts *Note*:
have no default value.
* [`tls.createServer()`][] sets the default value of the
`honorCipherOrder` option to `true`, other APIs that create secure contexts
leave it unset.
* [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value
generated from `process.argv` as the default value of the `sessionIdContext`
option, other APIs that create secure contexts have no default value.
The `tls.createSecureContext()` method creates a credentials object. The `tls.createSecureContext()` method creates a credentials object.
@ -1060,8 +1061,7 @@ changes:
server will time out. See [SSL_CTX_set_timeout] for more details. server will time out. See [SSL_CTX_set_timeout] for more details.
* `ticketKeys`: A 48-byte `Buffer` instance consisting of a 16-byte prefix, * `ticketKeys`: A 48-byte `Buffer` instance consisting of a 16-byte prefix,
a 16-byte HMAC key, and a 16-byte AES key. This can be used to accept TLS a 16-byte HMAC key, and a 16-byte AES key. This can be used to accept TLS
session tickets on multiple instances of the TLS server. *Note* that this is session tickets on multiple instances of the TLS server.
automatically shared between `cluster` module workers.
* ...: Any [`tls.createSecureContext()`][] options can be provided. For * ...: Any [`tls.createSecureContext()`][] options can be provided. For
servers, the identity options (`pfx` or `key`/`cert`) are usually required. servers, the identity options (`pfx` or `key`/`cert`) are usually required.
* `secureConnectionListener` {Function} * `secureConnectionListener` {Function}
@ -1069,6 +1069,9 @@ changes:
Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is
automatically set as a listener for the [`'secureConnection'`][] event. automatically set as a listener for the [`'secureConnection'`][] event.
*Note*: The `ticketKeys` options is automatically shared between `cluster`
module workers.
The following illustrates a simple echo server: The following illustrates a simple echo server:
```js ```js

6
doc/api/util.md
View File

@ -151,9 +151,9 @@ changes:
description: The `constructor` parameter can refer to an ES6 class now. description: The `constructor` parameter can refer to an ES6 class now.
--> -->
_Note: usage of `util.inherits()` is discouraged. Please use the ES6 `class` and *Note*: Usage of `util.inherits()` is discouraged. Please use the ES6 `class`
`extends` keywords to get language level inheritance support. Also note that and `extends` keywords to get language level inheritance support. Also note
the two styles are [semantically incompatible][]._ that the two styles are [semantically incompatible][].
* `constructor` {Function} * `constructor` {Function}
* `superConstructor` {Function} * `superConstructor` {Function}

8
doc/api/zlib.md
View File

@ -54,8 +54,8 @@ the compression encodings accepted by the client. The [`Content-Encoding`][]
header is used to identify the compression encodings actually applied to a header is used to identify the compression encodings actually applied to a
message. message.
**Note: the examples given below are drastically simplified to show *Note*: the examples given below are drastically simplified to show
the basic concept.** Using `zlib` encoding can be expensive, and the results the basic concept. Using `zlib` encoding can be expensive, and the results
ought to be cached. See [Memory Usage Tuning][] for more information ought to be cached. See [Memory Usage Tuning][] for more information
on the speed/memory/compression tradeoffs involved in `zlib` usage. on the speed/memory/compression tradeoffs involved in `zlib` usage.
@ -100,7 +100,7 @@ http.createServer((request, response) => {
acceptEncoding = ''; acceptEncoding = '';
} }
// Note: this is not a conformant accept-encoding parser. // Note: This is not a conformant accept-encoding parser.
// See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3 // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
if (acceptEncoding.match(/\bdeflate\b/)) { if (acceptEncoding.match(/\bdeflate\b/)) {
response.writeHead(200, { 'Content-Encoding': 'deflate' }); response.writeHead(200, { 'Content-Encoding': 'deflate' });
@ -437,7 +437,7 @@ added: v0.5.8
Returns a new [DeflateRaw][] object with an [options][]. Returns a new [DeflateRaw][] object with an [options][].
**Note:** The zlib library rejects requests for 256-byte windows (i.e., *Note*: The zlib library rejects requests for 256-byte windows (i.e.,
`{ windowBits: 8 }` in `options`). An `Error` will be thrown when creating `{ windowBits: 8 }` in `options`). An `Error` will be thrown when creating
a [DeflateRaw][] object with this specific value of the `windowBits` option. a [DeflateRaw][] object with this specific value of the `windowBits` option.

2
doc/changelogs/CHANGELOG_V010.md
View File

@ -70,7 +70,7 @@
* [io.js](CHANGELOG_IOJS.md) * [io.js](CHANGELOG_IOJS.md)
* [Archive](CHANGELOG_ARCHIVE.md) * [Archive](CHANGELOG_ARCHIVE.md)
**Note:** Node.js v0.10 is covered by the *Note*: Node.js v0.10 is covered by the
[Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and
will be maintained until October 2016. will be maintained until October 2016.

2
doc/changelogs/CHANGELOG_V012.md
View File

@ -38,7 +38,7 @@
* [io.js](CHANGELOG_IOJS.md) * [io.js](CHANGELOG_IOJS.md)
* [Archive](CHANGELOG_ARCHIVE.md) * [Archive](CHANGELOG_ARCHIVE.md)
**Note:** Node.js v0.12 is covered by the *Note*: Node.js v0.12 is covered by the
[Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and
will be maintained until December 31st, 2016. will be maintained until December 31st, 2016.

2
doc/changelogs/CHANGELOG_V4.md
View File

@ -57,7 +57,7 @@
* [Archive](CHANGELOG_ARCHIVE.md) * [Archive](CHANGELOG_ARCHIVE.md)
**Note:** Node.js v4 is covered by the *Note*: Node.js v4 is covered by the
[Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and
will be supported actively until April 2017 and maintained until April 2018. will be supported actively until April 2017 and maintained until April 2018.

2
doc/changelogs/CHANGELOG_V5.md
View File

@ -38,7 +38,7 @@
* [io.js](CHANGELOG_IOJS.md) * [io.js](CHANGELOG_IOJS.md)
* [Archive](CHANGELOG_ARCHIVE.md) * [Archive](CHANGELOG_ARCHIVE.md)
**Note:** Official support for the v5 release line is scheduled to expire *Note*: Official support for the v5 release line is scheduled to expire
around June 2016. Users of v5 should upgrade to [Node.js v6](CHANGELOG_V6.md). around June 2016. Users of v5 should upgrade to [Node.js v6](CHANGELOG_V6.md).
<a id="5.12.0"></a> <a id="5.12.0"></a>

2
doc/changelogs/CHANGELOG_V6.md
View File

@ -45,7 +45,7 @@
* [io.js](CHANGELOG_IOJS.md) * [io.js](CHANGELOG_IOJS.md)
* [Archive](CHANGELOG_ARCHIVE.md) * [Archive](CHANGELOG_ARCHIVE.md)
**Note:** Node.js v6 is covered by the *Note*: Node.js v6 is covered by the
[Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and
will be supported actively until April 2018 and maintained until April 2019. will be supported actively until April 2018 and maintained until April 2019.

5
doc/releases.md
View File

@ -86,7 +86,7 @@ This macro is used to signal an ABI version for native addons. It currently has
The general rule is to bump this version when there are _breaking ABI_ changes 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. The general rule is to bump this version when there are _breaking ABI_ changes 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** that 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. *Note*: 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.
### 3. Update the Changelog ### 3. Update the Changelog
@ -279,7 +279,8 @@ Use `tools/release.sh` to promote and sign the build. When run, it will perform
If you didn't wait for ARM builds in the previous step before promoting the 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. If you didn't wait for ARM builds in the previous step before promoting the 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 vX.Y.Z`. *Note*: It is possible to only sign a release by running
`./tools/release.sh -s vX.Y.Z`.
### 13. Check the Release ### 13. Check the Release

Write Preview
Loading…
Cancel
Save