diff options
author | Rich Trott <rtrott@gmail.com> | 2019-10-24 07:28:42 +0300 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2019-10-26 18:39:41 +0300 |
commit | 10040500da6af33b602e35c3f3bbe28cf76c4c4a (patch) | |
tree | 69c2af94709de9ef7022c41423c0f618eb0d5e0a /doc/api | |
parent | 6858c7e3e7c30986d68a683d3d5e4ede4c0b529f (diff) |
doc: remove dashes
The use of dashes -- in general, but especially in our docs -- can be
problematic. It is used inconsistently and there is always another form
of punctuation that is as good or better for the situation. In an effort
to reduce the number of variations we use to display the same types of
information, remove the various uses of dashes from the documentation.
PR-URL: https://github.com/nodejs/node/pull/30101
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/addons.md | 7 | ||||
-rw-r--r-- | doc/api/buffer.md | 20 | ||||
-rw-r--r-- | doc/api/child_process.md | 26 | ||||
-rw-r--r-- | doc/api/cli.md | 2 | ||||
-rw-r--r-- | doc/api/crypto.md | 16 | ||||
-rw-r--r-- | doc/api/debugger.md | 44 | ||||
-rw-r--r-- | doc/api/deprecations.md | 12 | ||||
-rw-r--r-- | doc/api/dgram.md | 8 | ||||
-rw-r--r-- | doc/api/esm.md | 2 | ||||
-rw-r--r-- | doc/api/fs.md | 58 | ||||
-rw-r--r-- | doc/api/http2.md | 78 | ||||
-rw-r--r-- | doc/api/index.md | 2 | ||||
-rw-r--r-- | doc/api/inspector.md | 2 | ||||
-rw-r--r-- | doc/api/modules.md | 12 | ||||
-rw-r--r-- | doc/api/n-api.md | 43 | ||||
-rw-r--r-- | doc/api/net.md | 22 | ||||
-rw-r--r-- | doc/api/policy.md | 7 | ||||
-rw-r--r-- | doc/api/process.md | 28 | ||||
-rw-r--r-- | doc/api/readline.md | 6 | ||||
-rw-r--r-- | doc/api/repl.md | 36 | ||||
-rw-r--r-- | doc/api/report.md | 15 | ||||
-rw-r--r-- | doc/api/stream.md | 10 | ||||
-rw-r--r-- | doc/api/tls.md | 8 | ||||
-rw-r--r-- | doc/api/tracing.md | 26 | ||||
-rw-r--r-- | doc/api/tty.md | 8 | ||||
-rw-r--r-- | doc/api/util.md | 42 |
26 files changed, 266 insertions, 274 deletions
diff --git a/doc/api/addons.md b/doc/api/addons.md index ca99e5e35d9..6b440bf6746 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -11,8 +11,7 @@ provide an interface between JavaScript running in Node.js and C/C++ libraries. There are three options for implementing Addons: N-API, nan, or direct use of internal V8, libuv and Node.js libraries. Unless you need direct access to functionality which is not exposed by N-API, use N-API. -Refer to the section [C/C++ Addons - N-API](n-api.html) -for more information on N-API. +Refer to [C/C++ Addons with N-API](n-api.html) for more information on N-API. When not using N-API, implementing Addons is complicated, involving knowledge of several components and APIs: @@ -435,8 +434,8 @@ NAPI_MODULE(NODE_GYP_MODULE_NAME, init) } // namespace demo ``` -The functions available and how to use them are documented in the -section titled [C/C++ Addons - N-API](n-api.html). +The functions available and how to use them are documented in +[C/C++ Addons with N-API](n-api.html). ## Addon examples diff --git a/doc/api/buffer.md b/doc/api/buffer.md index b1fa5167d0d..e46e7f0994c 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -182,28 +182,28 @@ console.log(Buffer.from('fhqwhgads', 'utf16le')); The character encodings currently supported by Node.js include: -* `'ascii'` - For 7-bit ASCII data only. This encoding is fast and will strip +* `'ascii'`: For 7-bit ASCII data only. This encoding is fast and will strip the high bit if set. -* `'utf8'` - Multibyte encoded Unicode characters. Many web pages and other +* `'utf8'`: Multibyte encoded Unicode characters. Many web pages and other document formats use UTF-8. -* `'utf16le'` - 2 or 4 bytes, little-endian encoded Unicode characters. +* `'utf16le'`: 2 or 4 bytes, little-endian encoded Unicode characters. Surrogate pairs (U+10000 to U+10FFFF) are supported. -* `'ucs2'` - Alias of `'utf16le'`. +* `'ucs2'`: Alias of `'utf16le'`. -* `'base64'` - Base64 encoding. When creating a `Buffer` from a string, +* `'base64'`: Base64 encoding. When creating a `Buffer` from a string, this encoding will also correctly accept "URL and Filename Safe Alphabet" as specified in [RFC 4648, Section 5][]. -* `'latin1'` - A way of encoding the `Buffer` into a one-byte encoded string +* `'latin1'`: A way of encoding the `Buffer` into a one-byte encoded string (as defined by the IANA in [RFC 1345][], page 63, to be the Latin-1 supplement block and C0/C1 control codes). -* `'binary'` - Alias for `'latin1'`. +* `'binary'`: Alias for `'latin1'`. -* `'hex'` - Encode each byte as two hexadecimal characters. +* `'hex'`: Encode each byte as two hexadecimal characters. Modern Web browsers follow the [WHATWG Encoding Standard][] which aliases both `'latin1'` and `'ISO-8859-1'` to `'win-1252'`. This means that while doing @@ -1003,8 +1003,8 @@ The index operator `[index]` can be used to get and set the octet at position range is between `0x00` and `0xFF` (hex) or `0` and `255` (decimal). This operator is inherited from `Uint8Array`, so its behavior on out-of-bounds -access is the same as `UInt8Array` - that is, getting returns `undefined` and -setting does nothing. +access is the same as `UInt8Array`. In other words, getting returns `undefined` +and setting does nothing. ```js // Copy an ASCII string into a `Buffer` one byte at a time. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 9f153175a1c..0f725f4fe1f 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -599,21 +599,21 @@ equal to `['pipe', 'pipe', 'pipe']`. For convenience, `options.stdio` may be one of the following strings: -* `'pipe'` - equivalent to `['pipe', 'pipe', 'pipe']` (the default) -* `'ignore'` - equivalent to `['ignore', 'ignore', 'ignore']` -* `'inherit'` - equivalent to `['inherit', 'inherit', 'inherit']` or `[0, 1, 2]` +* `'pipe'`: equivalent to `['pipe', 'pipe', 'pipe']` (the default) +* `'ignore'`: equivalent to `['ignore', 'ignore', 'ignore']` +* `'inherit'`: equivalent to `['inherit', 'inherit', 'inherit']` or `[0, 1, 2]` Otherwise, the value of `options.stdio` is an array where each index corresponds to an fd in the child. The fds 0, 1, and 2 correspond to stdin, stdout, and stderr, respectively. Additional fds can be specified to create additional pipes between the parent and child. The value is one of the following: -1. `'pipe'` - Create a pipe between the child process and the parent process. +1. `'pipe'`: Create a pipe between the child process and the parent process. The parent end of the pipe is exposed to the parent as a property on the `child_process` object as [`subprocess.stdio[fd]`][`subprocess.stdio`]. Pipes - created for fds 0 - 2 are also available as [`subprocess.stdin`][], + created for fds 0, 1, and 2 are also available as [`subprocess.stdin`][], [`subprocess.stdout`][] and [`subprocess.stderr`][], respectively. -2. `'ipc'` - Create an IPC channel for passing messages/file descriptors +2. `'ipc'`: Create an IPC channel for passing messages/file descriptors between parent and child. A [`ChildProcess`][] may have at most one IPC stdio file descriptor. Setting this option enables the [`subprocess.send()`][] method. If the child is a Node.js process, the @@ -624,25 +624,25 @@ pipes between the parent and child. The value is one of the following: Accessing the IPC channel fd in any way other than [`process.send()`][] or using the IPC channel with a child process that is not a Node.js instance is not supported. -3. `'ignore'` - Instructs Node.js to ignore the fd in the child. While Node.js - will always open fds 0 - 2 for the processes it spawns, setting the fd to - `'ignore'` will cause Node.js to open `/dev/null` and attach it to the +3. `'ignore'`: Instructs Node.js to ignore the fd in the child. While Node.js + will always open fds 0, 1, and 2 for the processes it spawns, setting the fd + to `'ignore'` will cause Node.js to open `/dev/null` and attach it to the child's fd. -4. `'inherit'` - Pass through the corresponding stdio stream to/from the +4. `'inherit'`: Pass through the corresponding stdio stream to/from the parent process. In the first three positions, this is equivalent to `process.stdin`, `process.stdout`, and `process.stderr`, respectively. In any other position, equivalent to `'ignore'`. -5. {Stream} object - Share a readable or writable stream that refers to a tty, +5. {Stream} object: Share a readable or writable stream that refers to a tty, file, socket, or a pipe with the child process. The stream's underlying file descriptor is duplicated in the child process to the fd that corresponds to the index in the `stdio` array. The stream must have an underlying descriptor (file streams do not until the `'open'` event has occurred). -6. Positive integer - The integer value is interpreted as a file descriptor +6. Positive integer: The integer value is interpreted as a file descriptor that is currently open in the parent process. It is shared with the child process, similar to how {Stream} objects can be shared. Passing sockets is not supported on Windows. -7. `null`, `undefined` - Use default value. For stdio fds 0, 1, and 2 (in other +7. `null`, `undefined`: Use default value. For stdio fds 0, 1, and 2 (in other words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the default is `'ignore'`. diff --git a/doc/api/cli.md b/doc/api/cli.md index 69e9e52a629..2830f903583 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -39,7 +39,7 @@ For example, `--pending-deprecation` is equivalent to `--pending_deprecation`. added: v8.0.0 --> -Alias for stdin, analogous to the use of - in other command line utilities, +Alias for stdin. Analogous to the use of `-` in other command line utilities, meaning that the script will be read from stdin, and the rest of the options are passed to that script. diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 1ab3dfeafe1..68c8ba0bb3e 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1417,7 +1417,7 @@ If `privateKey` is not a [`KeyObject`][], this function behaves as if `privateKey` had been passed to [`crypto.createPrivateKey()`][]. If it is an object, the following additional properties can be passed: -* `padding`: {integer} - Optional padding value for RSA, one of the following: +* `padding` {integer} Optional padding value for RSA, one of the following: * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -1425,7 +1425,7 @@ object, the following additional properties can be passed: used to sign the message as specified in section 3.1 of [RFC 4055][], unless an MGF1 hash function has been specified as part of the key in compliance with section 3.3 of [RFC 4055][]. -* `saltLength`: {integer} - salt length for when padding is +* `saltLength` {integer} Salt length for when padding is `RSA_PKCS1_PSS_PADDING`. The special value `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the @@ -1526,7 +1526,7 @@ If `object` is not a [`KeyObject`][], this function behaves as if `object` had been passed to [`crypto.createPublicKey()`][]. If it is an object, the following additional properties can be passed: -* `padding`: {integer} - Optional padding value for RSA, one of the following: +* `padding` {integer} Optional padding value for RSA, one of the following: * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -1534,7 +1534,7 @@ object, the following additional properties can be passed: used to verify the message as specified in section 3.1 of [RFC 4055][], unless an MGF1 hash function has been specified as part of the key in compliance with section 3.3 of [RFC 4055][]. -* `saltLength`: {integer} - salt length for when padding is +* `saltLength` {integer} Salt length for when padding is `RSA_PKCS1_PSS_PADDING`. The special value `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest size, `crypto.constants.RSA_PSS_SALTLEN_AUTO` (default) causes it to be @@ -2891,13 +2891,13 @@ If `key` is not a [`KeyObject`][], this function behaves as if `key` had been passed to [`crypto.createPrivateKey()`][]. If it is an object, the following additional properties can be passed: -* `padding`: {integer} - Optional padding value for RSA, one of the following: +* `padding` {integer} Optional padding value for RSA, one of the following: * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` `RSA_PKCS1_PSS_PADDING` will use MGF1 with the same hash function used to sign the message as specified in section 3.1 of [RFC 4055][]. -* `saltLength`: {integer} - salt length for when padding is +* `saltLength` {integer} Salt length for when padding is `RSA_PKCS1_PSS_PADDING`. The special value `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the @@ -2944,13 +2944,13 @@ If `key` is not a [`KeyObject`][], this function behaves as if `key` had been passed to [`crypto.createPublicKey()`][]. If it is an object, the following additional properties can be passed: -* `padding`: {integer} - Optional padding value for RSA, one of the following: +* `padding` {integer} Optional padding value for RSA, one of the following: * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` `RSA_PKCS1_PSS_PADDING` will use MGF1 with the same hash function used to sign the message as specified in section 3.1 of [RFC 4055][]. -* `saltLength`: {integer} - salt length for when padding is +* `saltLength` {integer} Salt length for when padding is `RSA_PKCS1_PSS_PADDING`. The special value `crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the diff --git a/doc/api/debugger.md b/doc/api/debugger.md index 318b44de61d..823574f1bc1 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -104,21 +104,21 @@ To begin watching an expression, type `watch('my_expression')`. The command ### Stepping -* `cont`, `c` - Continue execution -* `next`, `n` - Step next -* `step`, `s` - Step in -* `out`, `o` - Step out -* `pause` - Pause running code (like pause button in Developer Tools) +* `cont`, `c`: Continue execution +* `next`, `n`: Step next +* `step`, `s`: Step in +* `out`, `o`: Step out +* `pause`: Pause running code (like pause button in Developer Tools) ### Breakpoints -* `setBreakpoint()`, `sb()` - Set breakpoint on current line -* `setBreakpoint(line)`, `sb(line)` - Set breakpoint on specific line -* `setBreakpoint('fn()')`, `sb(...)` - Set breakpoint on a first statement in +* `setBreakpoint()`, `sb()`: Set breakpoint on current line +* `setBreakpoint(line)`, `sb(line)`: Set breakpoint on specific line +* `setBreakpoint('fn()')`, `sb(...)`: Set breakpoint on a first statement in functions body -* `setBreakpoint('script.js', 1)`, `sb(...)` - Set breakpoint on first line of +* `setBreakpoint('script.js', 1)`, `sb(...)`: Set breakpoint on first line of `script.js` -* `clearBreakpoint('script.js', 1)`, `cb(...)` - Clear breakpoint in `script.js` +* `clearBreakpoint('script.js', 1)`, `cb(...)`: Clear breakpoint in `script.js` on line 1 It is also possible to set a breakpoint in a file (module) that @@ -147,26 +147,26 @@ debug> ### Information -* `backtrace`, `bt` - Print backtrace of current execution frame -* `list(5)` - List scripts source code with 5 line context (5 lines before and +* `backtrace`, `bt`: Print backtrace of current execution frame +* `list(5)`: List scripts source code with 5 line context (5 lines before and after) -* `watch(expr)` - Add expression to watch list -* `unwatch(expr)` - Remove expression from watch list -* `watchers` - List all watchers and their values (automatically listed on each +* `watch(expr)`: Add expression to watch list +* `unwatch(expr)`: Remove expression from watch list +* `watchers`: List all watchers and their values (automatically listed on each breakpoint) -* `repl` - Open debugger's repl for evaluation in debugging script's context -* `exec expr` - Execute an expression in debugging script's context +* `repl`: Open debugger's repl for evaluation in debugging script's context +* `exec expr`: Execute an expression in debugging script's context ### Execution control -* `run` - Run script (automatically runs on debugger's start) -* `restart` - Restart script -* `kill` - Kill script +* `run`: Run script (automatically runs on debugger's start) +* `restart`: Restart script +* `kill`: Kill script ### Various -* `scripts` - List all loaded scripts -* `version` - Display V8's version +* `scripts`: List all loaded scripts +* `version`: Display V8's version ## Advanced Usage diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index ca832060e19..50303baa782 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -141,17 +141,17 @@ API usability issues that can lead to accidental security issues. As an alternative, use one of the following methods of constructing `Buffer` objects: -* [`Buffer.alloc(size[, fill[, encoding]])`][alloc] - Create a `Buffer` with +* [`Buffer.alloc(size[, fill[, encoding]])`][alloc]: Create a `Buffer` with *initialized* memory. -* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with +* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size]: Create a `Buffer` with *uninitialized* memory. -* [`Buffer.allocUnsafeSlow(size)`][] - Create a `Buffer` with *uninitialized* +* [`Buffer.allocUnsafeSlow(size)`][]: Create a `Buffer` with *uninitialized* memory. -* [`Buffer.from(array)`][] - Create a `Buffer` with a copy of `array` +* [`Buffer.from(array)`][]: Create a `Buffer` with a copy of `array` * [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - Create a `Buffer` that wraps the given `arrayBuffer`. -* [`Buffer.from(buffer)`][] - Create a `Buffer` that copies `buffer`. -* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` +* [`Buffer.from(buffer)`][]: Create a `Buffer` that copies `buffer`. +* [`Buffer.from(string[, encoding])`][from_string_encoding]: Create a `Buffer` that copies `string`. Without `--pending-deprecation`, runtime warnings occur only for code not in diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 894f64f36e1..aea51ad711c 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -706,8 +706,8 @@ changes: * `ipv6Only` {boolean} Setting `ipv6Only` to `true` will disable dual-stack support, i.e., binding to address `::` won't make `0.0.0.0` be bound. **Default:** `false`. - * `recvBufferSize` {number} - Sets the `SO_RCVBUF` socket value. - * `sendBufferSize` {number} - Sets the `SO_SNDBUF` socket value. + * `recvBufferSize` {number} Sets the `SO_RCVBUF` socket value. + * `sendBufferSize` {number} Sets the `SO_SNDBUF` socket value. * `lookup` {Function} Custom lookup function. **Default:** [`dns.lookup()`][]. * `callback` {Function} Attached as a listener for `'message'` events. Optional. * Returns: {dgram.Socket} @@ -725,8 +725,8 @@ and port can be retrieved using [`socket.address().address`][] and added: v0.1.99 --> -* `type` {string} - Either `'udp4'` or `'udp6'`. -* `callback` {Function} - Attached as a listener to `'message'` events. +* `type` {string} Either `'udp4'` or `'udp6'`. +* `callback` {Function} Attached as a listener to `'message'` events. * Returns: {dgram.Socket} Creates a `dgram.Socket` object of the specified `type`. diff --git a/doc/api/esm.md b/doc/api/esm.md index 298420465b6..5cb44868e8d 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -286,7 +286,7 @@ throw when an attempt is made to import them: ```js import submodule from 'es-module-package/private-module.js'; -// Throws - Module not found +// Throws ERR_MODULE_NOT_FOUND ``` > Note: this is not a strong encapsulation as any private modules can still be diff --git a/doc/api/fs.md b/doc/api/fs.md index 66cc7d7a7cc..78b7b3af2f8 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -982,15 +982,15 @@ representation. The times in the stat object have the following semantics: -* `atime` "Access Time" - Time when file data last accessed. Changed +* `atime` "Access Time": Time when file data last accessed. Changed by the mknod(2), utimes(2), and read(2) system calls. -* `mtime` "Modified Time" - Time when file data last modified. +* `mtime` "Modified Time": Time when file data last modified. Changed by the mknod(2), utimes(2), and write(2) system calls. -* `ctime` "Change Time" - Time when file status was last changed +* `ctime` "Change Time": Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2), and write(2) system calls. -* `birthtime` "Birth Time" - Time of file creation. Set once when the +* `birthtime` "Birth Time": Time of file creation. Set once when the file is created. On filesystems where birthtime is not available, this field may instead hold either the `ctime` or `1970-01-01T00:00Z` (ie, Unix epoch timestamp `0`). This value may be greater @@ -1571,12 +1571,12 @@ of the copy operation. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`). -* `fs.constants.COPYFILE_EXCL` - The copy operation will fail if `dest` already +* `fs.constants.COPYFILE_EXCL`: The copy operation will fail if `dest` already exists. -* `fs.constants.COPYFILE_FICLONE` - The copy operation will attempt to create a +* `fs.constants.COPYFILE_FICLONE`: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then a fallback copy mechanism is used. -* `fs.constants.COPYFILE_FICLONE_FORCE` - The copy operation will attempt to +* `fs.constants.COPYFILE_FICLONE_FORCE`: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then the operation will fail. @@ -1619,12 +1619,12 @@ of the copy operation. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`). -* `fs.constants.COPYFILE_EXCL` - The copy operation will fail if `dest` already +* `fs.constants.COPYFILE_EXCL`: The copy operation will fail if `dest` already exists. -* `fs.constants.COPYFILE_FICLONE` - The copy operation will attempt to create a +* `fs.constants.COPYFILE_FICLONE`: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then a fallback copy mechanism is used. -* `fs.constants.COPYFILE_FICLONE_FORCE` - The copy operation will attempt to +* `fs.constants.COPYFILE_FICLONE_FORCE`: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then the operation will fail. @@ -3834,7 +3834,7 @@ event (its disappearance). This happens when: * the file is deleted, followed by a restore -* the file is renamed twice - the second time back to its original name +* the file is renamed and then renamed a second time back to its original name ## fs.write(fd, buffer\[, offset\[, length\[, position\]\]\], callback) <!-- YAML @@ -4659,12 +4659,12 @@ of the copy operation. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`). -* `fs.constants.COPYFILE_EXCL` - The copy operation will fail if `dest` already +* `fs.constants.COPYFILE_EXCL`: The copy operation will fail if `dest` already exists. -* `fs.constants.COPYFILE_FICLONE` - The copy operation will attempt to create a +* `fs.constants.COPYFILE_FICLONE`: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then a fallback copy mechanism is used. -* `fs.constants.COPYFILE_FICLONE_FORCE` - The copy operation will attempt to +* `fs.constants.COPYFILE_FICLONE_FORCE`: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then the operation will fail. @@ -5371,31 +5371,31 @@ The following constants are meant for use with the [`fs.Stats`][] object's ## File System Flags The following flags are available wherever the `flag` option takes a -string: +string. -* `'a'` - Open file for appending. +* `'a'`: Open file for appending. The file is created if it does not exist. -* `'ax'` - Like `'a'` but fails if the path exists. +* `'ax'`: Like `'a'` but fails if the path exists. -* `'a+'` - Open file for reading and appending. +* `'a+'`: Open file for reading and appending. The file is created if it does not exist. -* `'ax+'` - Like `'a+'` but fails if the path exists. +* `'ax+'`: Like `'a+'` but fails if the path exists. -* `'as'` - Open file for appending in synchronous mode. +* `'as'`: Open file for appending in synchronous mode. The file is created if it does not exist. -* `'as+'` - Open file for reading and appending in synchronous mode. +* `'as+'`: Open file for reading and appending in synchronous mode. The file is created if it does not exist. -* `'r'` - Open file for reading. +* `'r'`: Open file for reading. An exception occurs if the file does not exist. -* `'r+'` - Open file for reading and writing. +* `'r+'`: Open file for reading and writing. An exception occurs if the file does not exist. -* `'rs+'` - Open file for reading and writing in synchronous mode. Instructs +* `'rs+'`: Open file for reading and writing in synchronous mode. Instructs the operating system to bypass the local file system cache. This is primarily useful for opening files on NFS mounts as it allows @@ -5406,15 +5406,15 @@ string: blocking call. If synchronous operation is desired, something like `fs.openSync()` should be used. -* `'w'` - Open file for writing. +* `'w'`: Open file for writing. The file is created (if it does not exist) or truncated (if it exists). -* `'wx'` - Like `'w'` but fails if the path exists. +* `'wx'`: Like `'w'` but fails if the path exists. -* `'w+'` - Open file for reading and writing. +* `'w+'`: Open file for reading and writing. The file is created (if it does not exist) or truncated (if it exists). -* `'wx+'` - Like `'w+'` but fails if the path exists. +* `'wx+'`: Like `'w+'` but fails if the path exists. `flag` can also be a number as documented by open(2); commonly used constants are available from `fs.constants`. On Windows, flags are translated to @@ -5434,7 +5434,7 @@ Modifying a file rather than replacing it may require a flags mode of `'r+'` rather than the default mode `'w'`. The behavior of some flags are platform-specific. As such, opening a directory -on macOS and Linux with the `'a+'` flag - see example below - will return an +on macOS and Linux with the `'a+'` flag, as in the example below, will return an error. In contrast, on Windows and FreeBSD, a file descriptor or a `FileHandle` will be returned. diff --git a/doc/api/http2.md b/doc/api/http2.md index fbd51fd86a6..058958517d4 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1982,21 +1982,19 @@ changes: serialized, compressed block of headers. Attempts to send headers that exceed this limit will result in a `'frameError'` event being emitted and the stream being closed and destroyed. - * `paddingStrategy` {number} Identifies the strategy used for determining the - amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + * `paddingStrategy` {number} The strategy used for determining the amount of + padding to use for `HEADERS` and `DATA` frames. **Default:** `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: - * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is - to be applied. - * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum - amount of padding, as determined by the internal implementation, is to - be applied. - * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply - enough padding to ensure that the total frame length, including the - 9-byte header, is a multiple of 8. For each frame, however, there is a - maximum allowed number of padding bytes that is determined by current - flow control state and settings. If this maximum is less than the - calculated amount needed to ensure alignment, the maximum will be used - and the total frame length will *not* necessarily be aligned at 8 bytes. + * `http2.constants.PADDING_STRATEGY_NONE`: No padding is applied. + * `http2.constants.PADDING_STRATEGY_MAX`: The maximum amount of padding, + determined by the internal implementation, is applied. + * `http2.constants.PADDING_STRATEGY_ALIGNED`: Attempts to apply enough + padding to ensure that the total frame length, including the 9-byte + header, is a multiple of 8. For each frame, there is a maximum allowed + number of padding bytes that is determined by current flow control state + and settings. If this maximum is less than the calculated amount needed to + ensure alignment, the maximum is used and the total frame length is not + necessarily aligned at 8 bytes. * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a `SETTINGS` frame had been received. Will be overridden if the remote peer sets its own value for @@ -2096,21 +2094,19 @@ changes: serialized, compressed block of headers. Attempts to send headers that exceed this limit will result in a `'frameError'` event being emitted and the stream being closed and destroyed. - * `paddingStrategy` {number} Identifies the strategy used for determining the - amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + * `paddingStrategy` {number} Strategy used for determining the amount of + padding to use for `HEADERS` and `DATA` frames. **Default:** `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: - * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is - to be applied. - * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum - amount of padding, as determined by the internal implementation, is to - be applied. - * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply - enough padding to ensure that the total frame length, including the - 9-byte header, is a multiple of 8. For each frame, however, there is a - maximum allowed number of padding bytes that is determined by current - flow control state and settings. If this maximum is less than the - calculated amount needed to ensure alignment, the maximum will be used - and the total frame length will *not* necessarily be aligned at 8 bytes. + * `http2.constants.PADDING_STRATEGY_NONE`: No padding is applied. + * `http2.constants.PADDING_STRATEGY_MAX`: The maximum amount of padding, + determined by the internal implementation, is applied. + * `http2.constants.PADDING_STRATEGY_ALIGNED`: Attempts to apply enough + padding to ensure that the total frame length, including the + 9-byte header, is a multiple of 8. For each frame, there is a maximum + allowed number of padding bytes that is determined by current flow control + state and settings. If this maximum is less than the calculated amount + needed to ensure alignment, the maximum is used and the total frame length + is not necessarily aligned at 8 bytes. * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a `SETTINGS` frame had been received. Will be overridden if the remote peer sets its own value for @@ -2196,21 +2192,19 @@ changes: serialized, compressed block of headers. Attempts to send headers that exceed this limit will result in a `'frameError'` event being emitted and the stream being closed and destroyed. - * `paddingStrategy` {number} Identifies the strategy used for determining the - amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + * `paddingStrategy` {number} Strategy used for determining the amount of + padding to use for `HEADERS` and `DATA` frames. **Default:** `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: - * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is - to be applied. - * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum - amount of padding, as determined by the internal implementation, is to - be applied. - * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply - enough padding to ensure that the total frame length, including the - 9-byte header, is a multiple of 8. For each frame, however, there is a - maximum allowed number of padding bytes that is determined by current - flow control state and settings. If this maximum is less than the - calculated amount needed to ensure alignment, the maximum will be used - and the total frame length will *not* necessarily be aligned at 8 bytes. + * `http2.constants.PADDING_STRATEGY_NONE`: No padding is applied. + * `http2.constants.PADDING_STRATEGY_MAX`: The maximum amount of padding, + determined by the internal implementation, is applied. + * `http2.constants.PADDING_STRATEGY_ALIGNED`: Attemps to apply enough + padding to ensure that the total frame length, including the + 9-byte header, is a multiple of 8. For each frame, there is a maximum + allowed number of padding bytes that is determined by current flow control + state and settings. If this maximum is less than the calculated amount + needed to ensure alignment, the maximum is used and the total frame length + is not necessarily aligned at 8 bytes. * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a `SETTINGS` frame had been received. Will be overridden if the remote peer sets its own value for diff --git a/doc/api/index.md b/doc/api/index.md index ad16610edaa..ceb3ce7f198 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -14,7 +14,7 @@ * [Async Hooks](async_hooks.html) * [Buffer](buffer.html) * [C++ Addons](addons.html) -* [C/C++ Addons - N-API](n-api.html) +* [C/C++ Addons with N-API](n-api.html) * [Child Processes](child_process.html) * [Cluster](cluster.html) * [Command Line Options](cli.html) diff --git a/doc/api/inspector.md b/doc/api/inspector.md index a5407cad336..41d96a0024e 100644 --- a/doc/api/inspector.md +++ b/doc/api/inspector.md @@ -152,7 +152,7 @@ added: v8.0.0 Posts a message to the inspector back-end. `callback` will be notified when a response is received. `callback` is a function that accepts two optional -arguments - error and message-specific result. +arguments: error and message-specific result. ```js session.post('Runtime.evaluate', { expression: '2 + 2' }, diff --git a/doc/api/modules.md b/doc/api/modules.md index 81f9d2d853f..76d61858854 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -103,13 +103,13 @@ resolves symlinks), and then looks for their dependencies in the `node_modules` folders as described [here](#modules_loading_from_node_modules_folders), this situation is very simple to resolve with the following architecture: -* `/usr/lib/node/foo/1.2.3/` - Contents of the `foo` package, version 1.2.3. -* `/usr/lib/node/bar/4.3.2/` - Contents of the `bar` package that `foo` - depends on. -* `/usr/lib/node/foo/1.2.3/node_modules/bar` - Symbolic link to +* `/usr/lib/node/foo/1.2.3/`: Contents of the `foo` package, version 1.2.3. +* `/usr/lib/node/bar/4.3.2/`: Contents of the `bar` package that `foo` depends + on. +* `/usr/lib/node/foo/1.2.3/node_modules/bar`: Symbolic link to `/usr/lib/node/bar/4.3.2/`. -* `/usr/lib/node/bar/4.3.2/node_modules/*` - Symbolic links to the packages - that `bar` depends on. +* `/usr/lib/node/bar/4.3.2/node_modules/*`: Symbolic links to the packages that + `bar` depends on. Thus, even if a cycle is encountered, or if there are dependency conflicts, every module will be able to get a version of its dependency diff --git a/doc/api/n-api.md b/doc/api/n-api.md index d608424c4c7..0ce1001325e 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1746,9 +1746,8 @@ Returns `napi_ok` if the API succeeded. This API returns an N-API value corresponding to a JavaScript `Array` type. The `Array`'s length property is set to the passed-in length parameter. However, the underlying buffer is not guaranteed to be pre-allocated by the VM -when the array is created - that behavior is left to the underlying VM -implementation. -If the buffer must be a contiguous block of memory that can be +when the array is created. That behavior is left to the underlying VM +implementation. If the buffer must be a contiguous block of memory that can be directly read and/or written via C, consider using [`napi_create_external_arraybuffer`][]. @@ -2469,18 +2468,18 @@ napi_status napi_get_typedarray_info(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] typedarray`: `napi_value` representing the `TypedArray` whose -properties to query. + properties to query. * `[out] type`: Scalar datatype of the elements within the `TypedArray`. * `[out] length`: The number of elements in the `TypedArray`. * `[out] data`: The data buffer underlying the `TypedArray` adjusted by -the `byte_offset` value so that it points to the first element in the -`TypedArray`. + the `byte_offset` value so that it points to the first element in the + `TypedArray`. * `[out] arraybuffer`: The `ArrayBuffer` underlying the `TypedArray`. * `[out] byte_offset`: The byte offset within the underlying native array -at which the first element of the arrays is located. The value for the data -parameter has already been adjusted so that data points to the first element -in the array. Therefore, the first byte of the native array would be at -data - `byte_offset`. + at which the first element of the arrays is located. The value for the data + parameter has already been adjusted so that data points to the first element + in the array. Therefore, the first byte of the native array would be at + `data - byte_offset`. Returns `napi_ok` if the API succeeded. @@ -2931,7 +2930,7 @@ Returns `napi_ok` if the API succeeded. This API returns the Undefined object. -## Working with JavaScript Values - Abstract Operations +## Working with JavaScript Values and Abstract Operations N-API exposes a set of APIs to perform some abstract operations on JavaScript values. Some of these operations are documented under [Section 7][] @@ -3418,17 +3417,15 @@ attributes listed in [Section 6.1.7.1][] of the [ECMAScript Language Specification][]. They can be one or more of the following bitflags: -* `napi_default` - Used to indicate that no explicit attributes are set on the -given property. By default, a property is read only, not enumerable and not -configurable. -* `napi_writable` - Used to indicate that a given property is writable. -* `napi_enumerable` - Used to indicate that a given property is enumerable. -* `napi_configurable` - Used to indicate that a given property is configurable, -as defined in [Section 6.1.7.1][] of the [ECMAScript Language Specification][]. -* `napi_static` - Used to indicate that the property will be defined as -a static property on a class as opposed to an instance property, which is the -default. This is used only by [`napi_define_class`][]. It is ignored by -`napi_define_properties`. +* `napi_default`: No explicit attributes are set on the property. By default, a + property is read only, not enumerable and not configurable. +* `napi_writable`: The property is writable. +* `napi_enumerable`: The property is enumerable. +* `napi_configurable`: The property is configurable as defined in + [Section 6.1.7.1][] of the [ECMAScript Language Specification][]. +* `napi_static`: The property will be defined as a static property on a class as + opposed to an instance property, which is the default. This is used only by + [`napi_define_class`][]. It is ignored by `napi_define_properties`. #### napi_property_descriptor @@ -4882,7 +4879,7 @@ napi_status napi_is_promise(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] promise`: The promise to examine * `[out] is_promise`: Flag indicating whether `promise` is a native promise -object - that is, a promise object created by the underlying engine. + object (that is, a promise object created by the underlying engine). ## Script execution diff --git a/doc/api/net.md b/doc/api/net.md index cd1b4f904ed..419bc8677fa 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -26,13 +26,13 @@ sockets on other operating systems. [`socket.connect()`][] take a `path` parameter to identify IPC endpoints. On Unix, the local domain is also known as the Unix domain. The path is a -filesystem pathname. It gets truncated to `sizeof(sockaddr_un.sun_path) - 1`, -which varies on different operating system between 91 and 107 bytes. -The typical values are 107 on Linux and 103 on macOS. The path is -subject to the same naming conventions and permissions checks as would be done -on file creation. If the Unix domain socket (that is visible as a file system -path) is created and used in conjunction with one of Node.js' API abstractions -such as [`net.createServer()`][], it will be unlinked as part of +filesystem pathname. It gets truncated to a length of +`sizeof(sockaddr_un.sun_path) - 1`, which varies 91 and 107 bytes depending on +the operating system. The typical values are 107 on Linux and 103 on macOS. The +path is subject to the same naming conventions and permissions checks as would +be done on file creation. If the Unix domain socket (that is visible as a file +system path) is created and used in conjunction with one of Node.js' API +abstractions such as [`net.createServer()`][], it will be unlinked as part of [`server.close()`][]. On the other hand, if it is created and used outside of these abstractions, the user will need to manually remove it. The same applies when the path was created by a Node.js API but the program crashes abruptly. @@ -550,7 +550,7 @@ added: v0.3.8 `net.Socket` has the property that `socket.write()` always works. This is to help users get up and running quickly. The computer cannot always keep up -with the amount of data that is written to a socket - the network connection +with the amount of data that is written to a socket. The network connection simply might be too slow. Node.js will internally queue up the data written to a socket and send it out over the wire when it is possible. (Internally it is polling on the socket's file descriptor for being writable). @@ -648,13 +648,13 @@ For [IPC][] connections, available `options` are: For both types, available `options` include: -* `onread` {Object} - If specified, incoming data is stored in a single `buffer` +* `onread` {Object} If specified, incoming data is stored in a single `buffer` and passed to the supplied `callback` when data arrives on the socket. Note: this will cause the streaming functionality to not provide any data, however events like `'error'`, `'end'`, and `'close'` will still be emitted as normal and methods like `pause()` and `resume()` will also behave as expected. - * `buffer` {Buffer|Uint8Array|Function} - Either a reusable chunk of memory to + * `buffer` {Buffer|Uint8Array|Function} Either a reusable chunk of memory to use for storing incoming data or a function that returns such. * `callback` {Function} This function is called for every chunk of incoming data. Two arguments are passed to it: the number of bytes written to @@ -943,7 +943,7 @@ buffer. Returns `false` if all or part of the data was queued in user memory. [`'drain'`][] will be emitted when the buffer is again free. The optional `callback` parameter will be executed when the data is finally -written out - this may not be immediately. +written out, which may not be immediately. See `Writable` stream [`write()`][stream_writable_write] method for more information. diff --git a/doc/api/policy.md b/doc/api/policy.md index f6e7e828501..bf4cc214552 100644 --- a/doc/api/policy.md +++ b/doc/api/policy.md @@ -56,10 +56,11 @@ It is possible to change the error behavior to one of a few possibilities by defining an "onerror" field in a policy manifest. The following values are available to change the behavior: -* `"exit"` - will exit the process immediately. +* `"exit"`: will exit the process immediately. No cleanup code will be allowed to run. -* `"log"` - will log the error at the site of the failure. -* `"throw"` (default) - will throw a JS error at the site of the failure. +* `"log"`: will log the error at the site of the failure. +* `"throw"`: will throw a JS error at the site of the failure. This is the + default. ```json { diff --git a/doc/api/process.md b/doc/api/process.md index eedbfeefdd7..a3fe44ba3c5 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -271,8 +271,8 @@ process will exit with a non-zero exit code and the stack trace will be printed. This is to avoid infinite recursion. Attempting to resume normally after an uncaught exception can be similar to -pulling out of the power cord when upgrading a computer — nine out of ten -times nothing happens - but the 10th time, the system becomes corrupted. +pulling out the power cord when upgrading a computer. Nine out of ten +times, nothing happens. But the tenth time, the system becomes corrupted. The correct use of `'uncaughtException'` is to perform synchronous cleanup of allocated resources (e.g. file descriptors, handles, etc) before shutting @@ -2381,40 +2381,40 @@ Node.js will normally exit with a `0` status code when no more async operations are pending. The following status codes are used in other cases: -* `1` **Uncaught Fatal Exception** - There was an uncaught exception, +* `1` **Uncaught Fatal Exception**: There was an uncaught exception, and it was not handled by a domain or an [`'uncaughtException'`][] event handler. -* `2` - Unused (reserved by Bash for builtin misuse) -* `3` **Internal JavaScript Parse Error** - The JavaScript source code +* `2`: Unused (reserved by Bash for builtin misuse) +* `3` **Internal JavaScript Parse Error**: The JavaScript source code internal in Node.js's bootstrapping process caused a parse error. This is extremely rare, and generally can only happen during development of Node.js itself. -* `4` **Internal JavaScript Evaluation Failure** - The JavaScript +* `4` **Internal JavaScript Evaluation Failure**: The JavaScript source code internal in Node.js's bootstrapping process failed to return a function value when evaluated. This is extremely rare, and generally can only happen during development of Node.js itself. -* `5` **Fatal Error** - There was a fatal unrecoverable error in V8. +* `5` **Fatal Error**: There was a fatal unrecoverable error in V8. Typically a message will be printed to stderr with the prefix `FATAL ERROR`. -* `6` **Non-function Internal Exception Handler** - There was an +* `6` **Non-function Internal Exception Handler**: There was an uncaught exception, but the internal fatal exception handler function was somehow set to a non-function, and could not be called. -* `7` **Internal Exception Handler Run-Time Failure** - There was an +* `7` **Internal Exception Handler Run-Time Failure**: There was an uncaught exception, and the internal fatal exception handler function itself threw an error while attempting to handle it. This can happen, for example, if an [`'uncaughtException'`][] or `domain.on('error')` handler throws an error. -* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes +* `8`: Unused. In previous versions of Node.js, exit code 8 sometimes indicated an uncaught exception. -* `9` - **Invalid Argument** - Either an unknown option was specified, +* `9` **Invalid Argument**: Either an unknown option was specified, or an option requiring a value was provided without a value. -* `10` **Internal JavaScript Run-Time Failure** - The JavaScript +* `10` **Internal JavaScript Run-Time Failure**: The JavaScript source code internal in Node.js's bootstrapping process threw an error when the bootstrapping function was called. This is extremely rare, and generally can only happen during development of Node.js itself. -* `12` **Invalid Debug Argument** - The `--inspect` and/or `--inspect-brk` +* `12` **Invalid Debug Argument**: The `--inspect` and/or `--inspect-brk` options were set, but the port number chosen was invalid or unavailable. -* `>128` **Signal Exits** - If Node.js receives a fatal signal such as +* `>128` **Signal Exits**: If Node.js receives a fatal signal such as `SIGKILL` or `SIGHUP`, then its exit code will be `128` plus the value of the signal code. This is a standard POSIX practice, since exit codes are defined to be 7-bit integers, and signal exits set diff --git a/doc/api/readline.md b/doc/api/readline.md index 642272e401e..ceda170bc2b 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -360,9 +360,9 @@ changes: * `stream` {stream.Writable} * `dir` {number} - * `-1` - to the left from cursor - * `1` - to the right from cursor - * `0` - the entire line + * `-1`: to the left from cursor + * `1`: to the right from cursor + * `0`: the entire line * `callback` {Function} Invoked once the operation completes. * Returns: {boolean} `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; diff --git a/doc/api/repl.md b/doc/api/repl.md index 81620e0e9b4..cd7edb59ddf 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -29,18 +29,18 @@ customizable evaluation functions. The following special commands are supported by all REPL instances: -* `.break` - When in the process of inputting a multi-line expression, entering +* `.break`: When in the process of inputting a multi-line expression, entering the `.break` command (or pressing the `<ctrl>-C` key combination) will abort further input or processing of that expression. -* `.clear` - Resets the REPL `context` to an empty object and clears any +* `.clear`: Resets the REPL `context` to an empty object and clears any multi-line expression currently being input. -* `.exit` - Close the I/O stream, causing the REPL to exit. -* `.help` - Show this list of special commands. -* `.save` - Save the current REPL session to a file: +* `.exit`: Close the I/O stream, causing the REPL to exit. +* `.help`: Show this list of special commands. +* `.save`: Save the current REPL session to a file: `> .save ./file/to/save.js` -* `.load` - Load a file into the current REPL session. +* `.load`: Load a file into the current REPL session. `> .load ./file/to/load.js` -* `.editor` - Enter editor mode (`<ctrl>-D` to finish, `<ctrl>-C` to cancel). +* `.editor`: Enter editor mode (`<ctrl>-D` to finish, `<ctrl>-C` to cancel). ```console > .editor @@ -58,11 +58,11 @@ welcome('Node.js User'); The following key combinations in the REPL have these special effects: -* `<ctrl>-C` - When pressed once, has the same effect as the `.break` command. +* `<ctrl>-C`: When pressed once, has the same effect as the `.break` command. When pressed twice on a blank line, has the same effect as the `.exit` command. -* `<ctrl>-D` - Has the same effect as the `.exit` command. -* `<tab>` - When pressed on a blank line, displays global and local (scope) +* `<ctrl>-D`: Has the same effect as the `.exit` command. +* `<tab>`: When pressed on a blank line, displays global and local (scope) variables. When pressed while entering other input, displays relevant autocompletion options. @@ -557,12 +557,12 @@ changes: * `replMode` {symbol} A flag that specifies whether the default evaluator executes all JavaScript commands in strict mode or default (sloppy) mode. Acceptable values are: - * `repl.REPL_MODE_SLOPPY` - evaluates expressions in sloppy mode. - * `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is + * `repl.REPL_MODE_SLOPPY` to evaluate expressions in sloppy mode. + * `repl.REPL_MODE_STRICT` to evaluate expressions in strict mode. This is equivalent to prefacing every repl statement with `'use strict'`. - * `breakEvalOnSigint` - Stop evaluating the current piece of code when - `SIGINT` is received, i.e. `Ctrl+C` is pressed. This cannot be used together - with a custom `eval` function. **Default:** `false`. + * `breakEvalOnSigint` {boolean} Stop evaluating the current piece of code when + `SIGINT` is received, such as when `Ctrl+C` is pressed. This cannot be used + together with a custom `eval` function. **Default:** `false`. * Returns: {repl.REPLServer} The `repl.start()` method creates and starts a [`repl.REPLServer`][] instance. @@ -601,16 +601,16 @@ undefined Various behaviors of the Node.js REPL can be customized using the following environment variables: -* `NODE_REPL_HISTORY` - When a valid path is given, persistent REPL history +* `NODE_REPL_HISTORY`: When a valid path is given, persistent REPL history will be saved to the specified file rather than `.node_repl_history` in the user's home directory. Setting this value to `''` (an empty string) will disable persistent REPL history. Whitespace will be trimmed from the value. On Windows platforms environment variables with empty values are invalid so set this variable to one or more spaces to disable persistent REPL history. -* `NODE_REPL_HISTORY_SIZE` - Controls how many lines of history will be +* `NODE_REPL_HISTORY_SIZE`: Controls how many lines of history will be persisted if history is available. Must be a positive number. **Default:** `1000`. -* `NODE_REPL_MODE` - May be either `'sloppy'` or `'strict'`. **Default:** +* `NODE_REPL_MODE`: May be either `'sloppy'` or `'strict'`. **Default:** `'sloppy'`, which will allow non-strict mode code to be run. ### Persistent History diff --git a/doc/api/report.md b/doc/api/report.md index d08de8636a3..b39a5286398 100644 --- a/doc/api/report.md +++ b/doc/api/report.md @@ -445,11 +445,11 @@ the name of a file into which the report is written. process.report.writeReport('./foo.json'); ``` -This function takes an optional additional argument `err` - an `Error` object -that will be used as the context for the JavaScript stack printed in the report. -When using report to handle errors in a callback or an exception handler, this -allows the report to include the location of the original error as well -as where it was handled. +This function takes an optional additional argument `err` which is an `Error` +object that will be used as the context for the JavaScript stack printed in the +report. When using report to handle errors in a callback or an exception +handler, this allows the report to include the location of the original error as +well as where it was handled. ```js try { @@ -483,8 +483,9 @@ console.log(typeof report === 'object'); // true console.log(JSON.stringify(report, null, 2)); ``` -This function takes an optional additional argument `err` - an `Error` object -that will be used as the context for the JavaScript stack printed in the report. +This function takes an optional additional argument `err`, which is an `Error` +object that will be used as the context for the JavaScript stack printed in the +report. ```js const report = process.report.getReport(new Error('custom error')); diff --git a/doc/api/stream.md b/doc/api/stream.md index ef0bbb50273..2e66bac0c04 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -33,13 +33,13 @@ second section explains how to create new types of streams. There are four fundamental stream types within Node.js: -* [`Writable`][] - streams to which data can be written (for example, +* [`Writable`][]: streams to which data can be written (for example, [`fs.createWriteStream()`][]). -* [`Readable`][] - streams from which data can be read (for example, +* [`Readable`][]: streams from which data can be read (for example, [`fs.createReadStream()`][]). -* [`Duplex`][] - streams that are both `Readable` and `Writable` (for example, +* [`Duplex`][]: streams that are both `Readable` and `Writable` (for example, [`net.Socket`][]). -* [`Transform`][] - `Duplex` streams that can modify or transform the data as it +* [`Transform`][]: `Duplex` streams that can modify or transform the data as it is written and read (for example, [`zlib.createDeflate()`][]). Additionally, this module includes the utility functions @@ -2508,7 +2508,7 @@ user programs. [`stream.write()`][stream-write]. * `encoding` {string} If the chunk is a string, then this is the encoding type. If chunk is a buffer, then this is the special - value - `'buffer'`, ignore it in this case. + value `'buffer'`. Ignore it in that case. * `callback` {Function} A callback function (optionally with an error argument and data) to be called after the supplied `chunk` has been processed. diff --git a/doc/api/tls.md b/doc/api/tls.md index 5529bd3529a..3fd8e8cb494 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -83,8 +83,8 @@ all sessions). Methods implementing this technique are called "ephemeral". Currently two methods are commonly used to achieve Perfect Forward Secrecy (note the character "E" appended to the traditional abbreviations): -* [DHE][] - An ephemeral version of the Diffie Hellman key-agreement protocol. -* [ECDHE][] - An ephemeral version of the Elliptic Curve Diffie Hellman +* [DHE][]: An ephemeral version of the Diffie Hellman key-agreement protocol. +* [ECDHE][]: An ephemeral version of the Elliptic Curve Diffie Hellman key-agreement protocol. Ephemeral methods may have some performance drawbacks, because key generation @@ -114,8 +114,8 @@ TLSv1.3, because all TLSv1.3 cipher suites use ECDHE. ALPN (Application-Layer Protocol Negotiation Extension) and SNI (Server Name Indication) are TLS handshake extensions: -* ALPN - Allows the use of one TLS server for multiple protocols (HTTP, HTTP/2) -* SNI - Allows the use of one TLS server for multiple hostnames with different +* ALPN: Allows the use of one TLS server for multiple protocols (HTTP, HTTP/2) +* SNI: Allows the use of one TLS server for multiple hostnames with different SSL certificates. ### Client-initiated renegotiation attack mitigation diff --git a/doc/api/tracing.md b/doc/api/tracing.md index 999c7d72301..596f624be54 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -13,26 +13,26 @@ accepts a list of comma-separated category names. The available categories are: -* `node` - An empty placeholder. -* `node.async_hooks` - Enables capture of detailed [`async_hooks`][] trace data. +* `node`: An empty placeholder. +* `node.async_hooks`: Enables capture of detailed [`async_hooks`][] trace data. The [`async_hooks`][] events have a unique `asyncId` and a special `triggerId` `triggerAsyncId` property. -* `node.bootstrap` - Enables capture of Node.js bootstrap milestones. -* `node.console` - Enables capture of `console.time()` and `console.count()` +* `node.bootstrap`: Enables capture of Node.js bootstrap milestones. +* `node.console`: Enables capture of `console.time()` and `console.count()` output. -* `node.dns.native` - Enables capture of trace data for DNS queries. -* `node.environment` - Enables capture of Node.js Environment milestones. -* `node.fs.sync` - Enables capture of trace data for file system sync methods. -* `node.perf` - Enables capture of [Performance API][] measurements. - * `node.perf.usertiming` - Enables capture of only Performance API User Timing +* `node.dns.native`: Enables capture of trace data for DNS queries. +* `node.environment`: Enables capture of Node.js Environment milestones. +* `node.fs.sync`: Enables capture of trace data for file system sync methods. +* `node.perf`: Enables capture of [Performance API][] measurements. + * `node.perf.usertiming`: Enables capture of only Performance API User Timing measures and marks. - * `node.perf.timerify` - Enables capture of only Performance API timerify + * `node.perf.timerify`: Enables capture of only Performance API timerify measurements. -* `node.promises.rejections` - Enables capture of trace data tracking the number +* `node.promises.rejections`: Enables capture of trace data tracking the number of unhandled Promise rejections and handled-after-rejections. -* `node.vm.script` - Enables capture of trace data for the `vm` module's +* `node.vm.script`: Enables capture of trace data for the `vm` module's `runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. -* `v8` - The [V8][] events are GC, compiling, and execution related. +* `v8`: The [V8][] events are GC, compiling, and execution related. By default the `node`, `node.async_hooks`, and `v8` categories are enabled. diff --git a/doc/api/tty.md b/doc/api/tty.md index 2f8e1de587c..186a236b57f 100644 --- a/doc/api/tty.md +++ b/doc/api/tty.md @@ -65,7 +65,7 @@ added: v0.7.7 raw device. If `false`, configures the `tty.ReadStream` to operate in its default mode. The `readStream.isRaw` property will be set to the resulting mode. -* Returns: {this} - the read stream instance. +* Returns: {this} The read stream instance. Allows configuration of `tty.ReadStream` so that it operates as a raw device. @@ -112,9 +112,9 @@ changes: --> * `dir` {number} - * `-1` - to the left from cursor - * `1` - to the right from cursor - * `0` - the entire line + * `-1`: to the left from cursor + * `1`: to the right from cursor + * `0`: the entire line * `callback` {Function} Invoked once the operation completes. * Returns: {boolean} `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional diff --git a/doc/api/util.md b/doc/api/util.md index 5cb5786a527..c87957b107e 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -225,27 +225,27 @@ as a `printf`-like format string which can contain zero or more format specifiers. Each specifier is replaced with the converted value from the corresponding argument. Supported specifiers are: -* `%s` - `String` will be used to convert all values except `BigInt`, `Object` +* `%s`: `String` will be used to convert all values except `BigInt`, `Object` and `-0`. `BigInt` values will be represented with an `n` and Objects that have no user defined `toString` function are inspected using `util.inspect()` with options `{ depth: 0, colors: false, compact: 3 }`. -* `%d` - `Number` will be used to convert all values except `BigInt` and +* `%d`: `Number` will be used to convert all values except `BigInt` and `Symbol`. -* `%i` - `parseInt(value, 10)` is used for all values except `BigInt` and +* `%i`: `parseInt(value, 10)` is used for all values except `BigInt` and `Symbol`. -* `%f` - `parseFloat(value)` is used for all values expect `Symbol`. -* `%j` - JSON. Replaced with the string `'[Circular]'` if the argument contains +* `%f`: `parseFloat(value)` is used for all values expect `Symbol`. +* `%j`: JSON. Replaced with the string `'[Circular]'` if the argument contains circular references. -* `%o` - `Object`. A string representation of an object with generic JavaScript +* `%o`: `Object`. A string representation of an object with generic JavaScript object formatting. Similar to `util.inspect()` with options `{ showHidden: true, showProxy: true }`. This will show the full object including non-enumerable properties and proxies. -* `%O` - `Object`. A string representation of an object with generic JavaScript +* `%O`: `Object`. A string representation of an object with generic JavaScript object formatting. Similar to `util.inspect()` without options. This will show the full object not including non-enumerable properties and proxies. -* `%c` - `CSS`. This specifier is currently ignored, and will skip any CSS +* `%c`: `CSS`. This specifier is currently ignored, and will skip any CSS passed in. -* `%%` - single percent sign (`'%'`). This does not consume an argument. +* `%%`: single percent sign (`'%'`). This does not consume an argument. * Returns: {string} The formatted string If a specifier does not have a corresponding argument, it is not replaced: @@ -665,18 +665,18 @@ via the `util.inspect.styles` and `util.inspect.colors` properties. The default styles and associated colors are: -* `bigint` - `yellow` -* `boolean` - `yellow` -* `date` - `magenta` -* `module` - `underline` -* `name` - (no styling) -* `null` - `bold` -* `number` - `yellow` -* `regexp` - `red` -* `special` - `cyan` (e.g., `Proxies`) -* `string` - `green` -* `symbol` - `green` -* `undefined` - `grey` +* `bigint`: `yellow` +* `boolean`: `yellow` +* `date`: `magenta` +* `module`: `underline` +* `name`: (no styling) +* `null`: `bold` +* `number`: `yellow` +* `regexp`: `red` +* `special`: `cyan` (e.g., `Proxies`) +* `string`: `green` +* `symbol`: `green` +* `undefined`: `grey` The predefined color codes are: `white`, `grey`, `black`, `blue`, `cyan`, `green`, `magenta`, `red` and `yellow`. There are also `bold`, `italic`, |