diff options
| -rw-r--r-- | doc/STYLE_GUIDE.md | 12 | ||||
| -rw-r--r-- | doc/api/addons.md | 4 | ||||
| -rw-r--r-- | doc/api/assert.md | 6 | ||||
| -rw-r--r-- | doc/api/async_hooks.md | 40 | ||||
| -rw-r--r-- | doc/api/buffer.md | 168 | ||||
| -rw-r--r-- | doc/api/child_process.md | 201 | ||||
| -rw-r--r-- | doc/api/cluster.md | 20 | ||||
| -rw-r--r-- | doc/api/dgram.md | 57 | ||||
| -rw-r--r-- | doc/api/net.md | 2 | ||||
| -rw-r--r-- | doc/api/stream.md | 2 |
10 files changed, 259 insertions, 253 deletions
diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 34879c1c7c..69bfa86500 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -65,8 +65,16 @@ * Make the "Note:" label italic, i.e. `*Note*:`. * Use a capital letter after the "Note:" label. * Preferably, make the note a new paragraph for better visual distinction. +* Function arguments or object properties should use the following format: + * <code>* \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`</code> + * E.g. <code>* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`</code> + * The `type` should refer to a Node.js type or a [JavaScript type][] +* Function returns should use the following format: + * <code>* Returns: {type|type2} Optional description.</code> + * E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code> -[plugin]: http://editorconfig.org/#download -[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma [Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash +[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types +[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma [The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage +[plugin]: http://editorconfig.org/#download diff --git a/doc/api/addons.md b/doc/api/addons.md index b031c273e7..3fd2ff5651 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -1060,8 +1060,8 @@ has ended but before the JavaScript VM is terminated and Node.js shuts down. #### void AtExit(callback, args) -* `callback`: `void (*)(void*)` - A pointer to the function to call at exit. -* `args`: `void*` - A pointer to pass to the callback at exit. +* `callback` {void (\*)(void\*)} A pointer to the function to call at exit. +* `args` {void\*} A pointer to pass to the callback at exit. Registers exit hooks that run after the event loop has ended but before the VM is killed. diff --git a/doc/api/assert.md b/doc/api/assert.md index a3cb02c7bc..4a6b06706f 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -306,9 +306,9 @@ added: v0.1.21 --> * `actual` {any} * `expected` {any} -* `message` {any} (default: 'Failed') -* `operator` {string} (default: '!=') -* `stackStartFunction` {function} (default: `assert.fail`) +* `message` {any} **Default:** `'Failed'` +* `operator` {string} **Default:** '!=' +* `stackStartFunction` {function} **Default:** `assert.fail` Throws an `AssertionError`. If `message` is falsy, the error message is set as the values of `actual` and `expected` separated by the provided `operator`. If diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 54b13f2f0a..863d21dd75 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -79,12 +79,12 @@ function promiseResolve(asyncId) { } added: REPLACEME --> -* `callbacks` {Object} the [Hook Callbacks][] to register +* `callbacks` {Object} The [Hook Callbacks][] to register * `init` {Function} The [`init` callback][]. * `before` {Function} The [`before` callback][]. * `after` {Function} The [`after` callback][]. * `destroy` {Function} The [`destroy` callback][]. -* Returns: `{AsyncHook}` instance used for disabling and enabling hooks +* Returns: `{AsyncHook}` Instance used for disabling and enabling hooks Registers functions to be called for different lifetime events of each async operation. @@ -168,7 +168,7 @@ doing this the otherwise infinite recursion is broken. #### `asyncHook.enable()` -* Returns {AsyncHook} A reference to `asyncHook`. +* Returns: {AsyncHook} A reference to `asyncHook`. Enable the callbacks for a given `AsyncHook` instance. If no callbacks are provided enabling is a noop. @@ -184,7 +184,7 @@ const hook = async_hooks.createHook(callbacks).enable(); #### `asyncHook.disable()` -* Returns {AsyncHook} A reference to `asyncHook`. +* Returns: {AsyncHook} A reference to `asyncHook`. Disable the callbacks for a given `AsyncHook` instance from the global pool of AsyncHook callbacks to be executed. Once a hook has been disabled it will not @@ -200,12 +200,12 @@ instance is destructed. ##### `init(asyncId, type, triggerAsyncId, resource)` -* `asyncId` {number} a unique ID for the async resource -* `type` {string} the type of the async resource -* `triggerAsyncId` {number} the unique ID of the async resource in whose - execution context this async resource was created -* `resource` {Object} reference to the resource representing the async operation, - needs to be released during _destroy_ +* `asyncId` {number} A unique ID for the async resource. +* `type` {string} The type of the async resource. +* `triggerAsyncId` {number} The unique ID of the async resource in whose + execution context this async resource was created. +* `resource` {Object} Reference to the resource representing the async operation, + needs to be released during _destroy_. Called when a class is constructed that has the _possibility_ to emit an asynchronous event. This _does not_ mean the instance must call @@ -468,7 +468,7 @@ init for PROMISE with id 6, trigger id: 5 # the Promise returned by then() #### `async_hooks.executionAsyncId()` -* Returns {number} the `asyncId` of the current execution context. Useful to +* Returns: {number} The `asyncId` of the current execution context. Useful to track when something calls. For example: @@ -502,7 +502,7 @@ const server = net.createServer(function onConnection(conn) { #### `async_hooks.triggerAsyncId()` -* Returns {number} the ID of the resource responsible for calling the callback +* Returns: {number} The ID of the resource responsible for calling the callback that is currently being executed. For example: @@ -569,9 +569,9 @@ asyncResource.triggerAsyncId(); #### `AsyncResource(type[, triggerAsyncId])` * arguments - * `type` {string} the type of async event - * `triggerAsyncId` {number} the ID of the execution context that created this - async event + * `type` {string} The type of async event. + * `triggerAsyncId` {number} The ID of the execution context that created this + async event. Example usage: @@ -599,7 +599,7 @@ class DBQuery extends AsyncResource { #### `asyncResource.emitBefore()` -* Returns {undefined} +* Returns: {undefined} Call all `before` callbacks to notify that a new asynchronous execution context is being entered. If nested calls to `emitBefore()` are made, the stack of @@ -607,7 +607,7 @@ is being entered. If nested calls to `emitBefore()` are made, the stack of #### `asyncResource.emitAfter()` -* Returns {undefined} +* Returns: {undefined} Call all `after` callbacks. If nested calls to `emitBefore()` were made, then make sure the stack is unwound properly. Otherwise an error will be thrown. @@ -618,7 +618,7 @@ called for all `asyncId`s on the stack if the error is handled by a domain or #### `asyncResource.emitDestroy()` -* Returns {undefined} +* Returns: {undefined} Call all `destroy` hooks. This should only ever be called once. An error will be thrown if it is called more than once. This **must** be manually called. If @@ -627,11 +627,11 @@ never be called. #### `asyncResource.asyncId()` -* Returns {number} the unique `asyncId` assigned to the resource. +* Returns: {number} The unique `asyncId` assigned to the resource. #### `asyncResource.triggerAsyncId()` -* Returns {number} the same `triggerAsyncId` that is passed to the `AsyncResource` +* Returns: {number} The same `triggerAsyncId` that is passed to the `AsyncResource` constructor. [`after` callback]: #async_hooks_after_asyncid diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 0b01370f90..cc3992b951 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -172,7 +172,7 @@ console.log(buf.toString('base64')); 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 @@ -330,7 +330,7 @@ changes: > Stability: 0 - Deprecated: Use [`Buffer.from(array)`] instead. -* `array` {Array} An array of bytes to copy from +* `array` {integer[]} An array of bytes to copy from. Allocates a new `Buffer` using an `array` of octets. @@ -410,7 +410,7 @@ changes: > Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead. -* `buffer` {Buffer} An existing `Buffer` to copy data from +* `buffer` {Buffer} An existing `Buffer` to copy data from. Copies the passed `buffer` data onto a new `Buffer` instance. @@ -447,7 +447,7 @@ changes: > Stability: 0 - Deprecated: Use [`Buffer.alloc()`] instead (also see > [`Buffer.allocUnsafe()`]). -* `size` {integer} The desired length of the new `Buffer` +* `size` {integer} The desired length of the new `Buffer`. Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be @@ -483,7 +483,7 @@ changes: > Stability: 0 - Deprecated: > Use [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] instead. -* `string` {string} String to encode +* `string` {string} String to encode. * `encoding` {string} The encoding of `string`. **Default:** `'utf8'` Creates a new `Buffer` containing the given JavaScript string `string`. If @@ -512,7 +512,7 @@ console.log(buf2.toString()); added: v5.10.0 --> -* `size` {integer} The desired length of the new `Buffer` +* `size` {integer} The desired length of the new `Buffer`. * `fill` {string|Buffer|integer} A value to pre-fill the new `Buffer` with. **Default:** `0` * `encoding` {string} If `fill` is a string, this is its encoding. @@ -573,7 +573,7 @@ changes: description: Passing a negative `size` will now throw an error. --> -* `size` {integer} The desired length of the new `Buffer` +* `size` {integer} The desired length of the new `Buffer`. Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be @@ -619,7 +619,7 @@ additional performance that [`Buffer.allocUnsafe()`] provides. added: v5.12.0 --> -* `size` {integer} The desired length of the new `Buffer` +* `size` {integer} The desired length of the new `Buffer`. Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be @@ -680,10 +680,10 @@ changes: --> * `string` {string|Buffer|TypedArray|DataView|ArrayBuffer} A value to - calculate the length of + calculate the length of. * `encoding` {string} If `string` is a string, this is its encoding. **Default:** `'utf8'` -* Returns: {integer} The number of bytes contained within `string` +* Returns: {integer} The number of bytes contained within `string`. 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 @@ -744,9 +744,9 @@ changes: description: The elements of `list` can now be `Uint8Array`s. --> -* `list` {Array} List of `Buffer` or [`Uint8Array`] instances to concat +* `list` {Array} List of `Buffer` or [`Uint8Array`] instances to concat. * `totalLength` {integer} Total length of the `Buffer` instances in `list` - when concatenated + when concatenated. * Returns: {Buffer} Returns a new `Buffer` which is the result of concatenating all the `Buffer` @@ -859,7 +859,7 @@ A `TypeError` will be thrown if `arrayBuffer` is not an [`ArrayBuffer`]. added: v5.10.0 --> -* `buffer` {Buffer} An existing `Buffer` to copy data from +* `buffer` {Buffer} An existing `Buffer` to copy data from. Copies the passed `buffer` data onto a new `Buffer` instance. @@ -964,7 +964,7 @@ Returns `true` if `obj` is a `Buffer`, `false` otherwise. added: v0.9.1 --> -* `encoding` {string} A character encoding name to check +* `encoding` {string} A character encoding name to check. * Returns: {boolean} Returns `true` if `encoding` contains a supported character encoding, or `false` @@ -1033,7 +1033,7 @@ changes: description: Additional parameters for specifying offsets are supported now. --> -* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to compare to +* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to compare to. * `targetStart` {integer} The offset within `target` at which to begin comparison. **Default:** `0` * `targetEnd` {integer} The offset with `target` at which to end comparison @@ -1192,7 +1192,7 @@ changes: description: The arguments can now be `Uint8Array`s. --> -* `otherBuffer` {Buffer} A `Buffer` or [`Uint8Array`] to compare to +* `otherBuffer` {Buffer} A `Buffer` or [`Uint8Array`] to compare to. * Returns: {boolean} Returns `true` if both `buf` and `otherBuffer` have exactly the same bytes, @@ -1221,12 +1221,12 @@ changes: description: The `encoding` parameter is supported now. --> -* `value` {string|Buffer|integer} The value to fill `buf` with -* `offset` {integer} Where to start filling `buf`. **Default:** `0` +* `value` {string|Buffer|integer} The value to fill `buf` with. +* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0` * `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`] * `encoding` {string} If `value` is a string, this is its encoding. **Default:** `'utf8'` -* Returns: {Buffer} A reference to `buf` +* Returns: {Buffer} A reference to `buf`. Fills `buf` with the specified `value`. If the `offset` and `end` are not given, the entire `buf` will be filled. This is meant to be a small simplification to @@ -1258,11 +1258,11 @@ console.log(Buffer.allocUnsafe(3).fill('\u0222')); added: v5.3.0 --> -* `value` {string|Buffer|integer} What to search for +* `value` {string|Buffer|integer} What to search for. * `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0` * `encoding` {string} If `value` is a string, this is its encoding. **Default:** `'utf8'` -* Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise +* Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise. Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`]. @@ -1307,12 +1307,12 @@ changes: is no longer required. --> -* `value` {string|Buffer|Uint8Array|integer} What to search for +* `value` {string|Buffer|Uint8Array|integer} What to search for. * `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0` * `encoding` {string} If `value` is a string, this is its encoding. **Default:** `'utf8'` * Returns: {integer} The index of the first occurrence of `value` in `buf` or `-1` - if `buf` does not contain `value` + if `buf` does not contain `value`. If `value` is: @@ -1420,13 +1420,13 @@ changes: description: The `value` can now be a `Uint8Array`. --> -* `value` {string|Buffer|Uint8Array|integer} What to search for +* `value` {string|Buffer|Uint8Array|integer} What to search for. * `byteOffset` {integer} Where to begin searching in `buf`. **Default:** [`buf.length`]` - 1` * `encoding` {string} If `value` is a string, this is its encoding. **Default:** `'utf8'` * Returns: {integer} The index of the last occurrence of `value` in `buf` or `-1` - if `buf` does not contain `value` + if `buf` does not contain `value`. Identical to [`buf.indexOf()`], except `buf` is searched from back to front instead of front to back. @@ -1557,7 +1557,7 @@ The `buf.parent` property is a deprecated alias for `buf.buffer`. added: v0.11.15 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 8` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 8`. * `noAssert` {boolean} Skip `offset` validation? **Default:** `false` * Returns: {number} @@ -1593,7 +1593,7 @@ console.log(buf.readDoubleLE(1, true)); added: v0.11.15 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 4` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 4`. * `noAssert` {boolean} Skip `offset` validation? **Default:** `false` * Returns: {number} @@ -1628,7 +1628,7 @@ console.log(buf.readFloatLE(1, true)); added: v0.5.0 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 1` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 1`. * `noAssert` {boolean} Skip `offset` validation? **Default:** `false` * Returns: {integer} @@ -1660,7 +1660,7 @@ console.log(buf.readInt8(2)); added: v0.5.5 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 2` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 2`. * `noAssert` {boolean} Skip `offset` validation? **Default:** `false` * Returns: {integer} @@ -1694,7 +1694,7 @@ console.log(buf.readInt16LE(1)); added: v0.5.5 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 4` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 4`. * `noAssert` {boolean} Skip `offset` validation? **Default:** `false` * Returns: {integer} @@ -1728,9 +1728,9 @@ console.log(buf.readInt32LE(1)); added: v0.11.15 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - byteLength` -* `byteLength` {integer} How many bytes to read. Must satisfy: `0 < byteLength <= 6` -* `noAssert` {boolean} Skip `offset` and `byteLength` validation? **Default:** `false` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - byteLength`. +* `byteLength` {integer} Number of bytes to read. Must satisfy: `0 < byteLength <= 6`. +* `noAssert` {boolean} Skip `offset` and `byteLength` validation? **Default:** `false`. * Returns: {integer} Reads `byteLength` number of bytes from `buf` at the specified `offset` @@ -1760,7 +1760,7 @@ console.log(buf.readIntBE(1, 6).toString(16)); added: v0.5.0 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 1` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 1`. * `noAssert` {boolean} Skip `offset` validation? **Default:** `false` * Returns: {integer} @@ -1790,7 +1790,7 @@ console.log(buf.readUInt8(2)); added: v0.5.5 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 2` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 2`. * `noAssert` {boolean} Skip `offset` validation? **Default:** `false` * Returns: {integer} @@ -1828,7 +1828,7 @@ console.log(buf.readUInt16LE(2).toString(16)); added: v0.5.5 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - 4` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 4`. * `noAssert` {boolean} Skip `offset` validation? **Default:** `false` * Returns: {integer} @@ -1860,8 +1860,8 @@ console.log(buf.readUInt32LE(1).toString(16)); added: v0.11.15 --> -* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - byteLength` -* `byteLength` {integer} How many bytes to read. Must satisfy: `0 < byteLength <= 6` +* `offset` {integer} Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - byteLength`. +* `byteLength` {integer} Number of bytes to read. Must satisfy: `0 < byteLength <= 6`. * `noAssert` {boolean} Skip `offset` and `byteLength` validation? **Default:** `false` * Returns: {integer} @@ -1963,7 +1963,7 @@ console.log(buf.slice(-5, -2).toString()); added: v5.10.0 --> -* Returns: {Buffer} A reference to `buf` +* Returns: {Buffer} A reference to `buf`. Interprets `buf` as an array of unsigned 16-bit integers and swaps the byte-order *in-place*. Throws a `RangeError` if [`buf.length`] is not a multiple of 2. @@ -1993,7 +1993,7 @@ buf2.swap16(); added: v5.10.0 --> -* Returns: {Buffer} A reference to `buf` +* Returns: {Buffer} A reference to `buf`. Interprets `buf` as an array of unsigned 32-bit integers and swaps the byte-order *in-place*. Throws a `RangeError` if [`buf.length`] is not a multiple of 4. @@ -2023,7 +2023,7 @@ buf2.swap32(); added: v6.3.0 --> -* Returns: {Buffer} A reference to `buf` +* Returns: {Buffer} A reference to `buf`. Interprets `buf` as an array of 64-bit numbers and swaps the byte-order *in-place*. Throws a `RangeError` if [`buf.length`] is not a multiple of 8. @@ -2169,11 +2169,11 @@ for (const value of buf) { added: v0.1.90 --> -* `string` {string} String to be written to `buf` -* `offset` {integer} Where to start writing `string`. **Default:** `0` -* `length` {integer} How many bytes to write. **Default:** `buf.length - offset` +* `string` {string} String to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write `string`. **Default:** `0` +* `length` {integer} Number of bytes to write. **Default:** `buf.length - offset` * `encoding` {string} The character encoding of `string`. **Default:** `'utf8'` -* Returns: {integer} Number of bytes written +* Returns: {integer} Number of bytes written. Writes `string` to `buf` at `offset` according to the character encoding in `encoding`. The `length` parameter is the number of bytes to write. If `buf` did not contain @@ -2197,10 +2197,10 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`); added: v0.11.15 --> -* `value` {number} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 8` +* `value` {number} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 8`. * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `value` to `buf` at the specified `offset` with specified endian format (`writeDoubleBE()` writes big endian, `writeDoubleLE()` writes little @@ -2232,10 +2232,10 @@ console.log(buf); added: v0.11.15 --> -* `value` {number} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 4` +* `value` {number} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 4`. * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `value` to `buf` at the specified `offset` with specified endian format (`writeFloatBE()` writes big endian, `writeFloatLE()` writes little @@ -2266,10 +2266,10 @@ console.log(buf); added: v0.5.0 --> -* `value` {integer} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 1` +* `value` {integer} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 1`. * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `value` to `buf` at the specified `offset`. `value` *should* be a valid signed 8-bit integer. Behavior is undefined when `value` is anything other than @@ -2298,10 +2298,10 @@ console.log(buf); added: v0.5.5 --> -* `value` {integer} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 2` +* `value` {integer} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 2`. * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `value` to `buf` at the specified `offset` with specified endian format (`writeInt16BE()` writes big endian, `writeInt16LE()` writes little @@ -2331,10 +2331,10 @@ console.log(buf); added: v0.5.5 --> -* `value` {integer} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 4` +* `value` {integer} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 4`. * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `value` to `buf` at the specified `offset` with specified endian format (`writeInt32BE()` writes big endian, `writeInt32LE()` writes little @@ -2364,12 +2364,12 @@ console.log(buf); added: v0.11.15 --> -* `value` {integer} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - byteLength` -* `byteLength` {integer} How many bytes to write. Must satisfy: `0 < byteLength <= 6` +* `value` {integer} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - byteLength`. +* `byteLength` {integer} Number of bytes to write. Must satisfy: `0 < byteLength <= 6`. * `noAssert` {boolean} Skip `value`, `offset`, and `byteLength` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `byteLength` bytes of `value` to `buf` at the specified `offset`. Supports up to 48 bits of accuracy. Behavior is undefined when `value` is @@ -2399,10 +2399,10 @@ console.log(buf); added: v0.5.0 --> -* `value` {integer} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 1` +* `value` {integer} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 1`. * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `value` to `buf` at the specified `offset`. `value` *should* be a valid unsigned 8-bit integer. Behavior is undefined when `value` is anything @@ -2431,10 +2431,10 @@ console.log(buf); added: v0.5.5 --> -* `value` {integer} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 2` +* `value` {integer} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 2`. * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `value` to `buf` at the specified `offset` with specified endian format (`writeUInt16BE()` writes big endian, `writeUInt16LE()` writes little @@ -2468,10 +2468,10 @@ console.log(buf); added: v0.5.5 --> -* `value` {integer} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - 4` +* `value` {integer} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 4`. * `noAssert` {boolean} Skip `value` and `offset` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `value` to `buf` at the specified `offset` with specified endian format (`writeUInt32BE()` writes big endian, `writeUInt32LE()` writes little @@ -2503,12 +2503,12 @@ console.log(buf); added: v0.5.5 --> -* `value` {integer} Number to be written to `buf` -* `offset` {integer} Where to start writing. Must satisfy: `0 <= offset <= buf.length - byteLength` -* `byteLength` {integer} How many bytes to write. Must satisfy: `0 < byteLength <= 6` +* `value` {integer} Number to be written to `buf`. +* `offset` {integer} Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - byteLength`. +* `byteLength` {integer} Number of bytes to write. Must satisfy: `0 < byteLength <= 6`. * `noAssert` {boolean} Skip `value`, `offset`, and `byteLength` validation? **Default:** `false` -* Returns: {integer} `offset` plus the number of bytes written +* Returns: {integer} `offset` plus the number of bytes written. Writes `byteLength` bytes of `value` to `buf` at the specified `offset`. Supports up to 48 bits of accuracy. Behavior is undefined when `value` is @@ -2552,7 +2552,7 @@ Note that this is a property on the `buffer` module returned by added: v3.0.0 --> -* {integer} The largest size allowed for a single `Buffer` instance +* {integer} The largest size allowed for a single `Buffer` instance. An alias for [`buffer.constants.MAX_LENGTH`][] @@ -2568,9 +2568,9 @@ changes: description: The `source` parameter can now be a `Uint8Array`. --> -* `source` {Buffer|Uint8Array} A `Buffer` or `Uint8Array` instance -* `fromEnc` {string} The current encoding -* `toEnc` {string} To target encoding +* `source` {Buffer|Uint8Array} A `Buffer` or `Uint8Array` instance. +* `fromEnc` {string} The current encoding. +* `toEnc` {string} To target encoding. Re-encodes the given `Buffer` or `Uint8Array` instance from one character encoding to another. Returns a new `Buffer` instance. @@ -2642,7 +2642,7 @@ deprecated: v6.0.0 > Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`] instead. -* `size` {integer} The desired length of the new `SlowBuffer` +* `size` {integer} The desired length of the new `SlowBuffer`. Allocates a new `Buffer` of `size` bytes. If the `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, a [`RangeError`] will be @@ -2681,7 +2681,7 @@ Note that `buffer.constants` is a property on the `buffer` module returned by added: 8.2.0 --> -* {integer} The largest size allowed for a single `Buffer` instance +* {integer} The largest size allowed for a single `Buffer` instance. On 32-bit architectures, this value is `(2^30)-1` (~1GB). On 64-bit architectures, this value is `(2^31)-1` (~2GB). @@ -2693,7 +2693,7 @@ This value is also available as [`buffer.kMaxLength`][]. added: 8.2.0 --> -* {integer} The largest length allowed for a single `string` instance +* {integer} The largest length allowed for a single `string` instance. Represents the largest `length` that a `string` primitive can have, counted in UTF-16 code units. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 573e1632ca..32c9c4f061 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -129,22 +129,23 @@ exec('"my script.cmd" a b', (err, stdout, stderr) => { added: v0.1.90 --> -* `command` {string} The command to run, with space-separated arguments +* `command` {string} The command to run, with space-separated arguments. * `options` {Object} - * `cwd` {string} Current working directory of the child process - * `env` {Object} Environment key-value pairs - * `encoding` {string} (Default: `'utf8'`) - * `shell` {string} Shell to execute the command with - (Default: `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See - [Shell Requirements][] and [Default Windows Shell][].) * `timeout` {number} (Default: `0`) + * `cwd` {string} Current working directory of the child process. + * `env` {Object} Environment key-value pairs. + * `encoding` {string} **Default:** `'utf8'` + * `shell` {string} Shell to execute the command with. + **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See + [Shell Requirements][] and [Default Windows Shell][]. + * `timeout` {number} **Default:** `0` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. (Default: `200*1024`) If exceeded, the child process is terminated. + stderr. **Default:** `200*1024`. If exceeded, the child process is terminated. See caveat at [`maxBuffer` and Unicode][]. - * `killSignal` {string|integer} (Default: `'SIGTERM'`) - * `uid` {number} Sets the user identity of the process. (See setuid(2).) - * `gid` {number} Sets the group identity of the process. (See setgid(2).) -* `callback` {Function} called with the output when process terminates + * `killSignal` {string|integer} **Default:** `'SIGTERM'` + * `uid` {number} Sets the user identity of the process (see setuid(2)). + * `gid` {number} Sets the group identity of the process (see setgid(2)). +* `callback` {Function} called with the output when process terminates. * `error` {Error} * `stdout` {string|Buffer} * `stderr` {string|Buffer} @@ -239,20 +240,20 @@ lsExample(); added: v0.1.91 --> -* `file` {string} The name or path of the executable file to run -* `args` {Array} List of string arguments +* `file` {string} The name or path of the executable file to run. +* `args` {string[]} List of string arguments. * `options` {Object} - * `cwd` {string} Current working directory of the child process - * `env` {Object} Environment key-value pairs - * `encoding` {string} (Default: `'utf8'`) - * `timeout` {number} (Default: `0`) + * `cwd` {string} Current working directory of the child process. + * `env` {Object} Environment key-value pairs. + * `encoding` {string} **Default:** `'utf8'` + * `timeout` {number} **Default:** `0` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. (Default: `200*1024`) If exceeded, the child process is terminated. + stderr. **Default:** `200*1024` If exceeded, the child process is terminated. See caveat at [`maxBuffer` and Unicode][]. - * `killSignal` {string|integer} (Default: `'SIGTERM'`) - * `uid` {number} Sets the user identity of the process. (See setuid(2).) - * `gid` {number} Sets the group identity of the process. (See setgid(2).) -* `callback` {Function} called with the output when process terminates + * `killSignal` {string|integer} **Default:** `'SIGTERM'` + * `uid` {number} Sets the user identity of the process (see setuid(2)). + * `gid` {number} Sets the group identity of the process (see setgid(2)). +* `callback` {Function} Called with the output when process terminates. * `error` {Error} * `stdout` {string|Buffer} * `stderr` {string|Buffer} @@ -310,24 +311,24 @@ changes: description: The `stdio` option is supported now. --> -* `modulePath` {string} The module to run in the child -* `args` {Array} List of string arguments +* `modulePath` {string} The module to run in the child. +* `args` {Array} List of string arguments. * `options` {Object} - * `cwd` {string} Current working directory of the child process - * `env` {Object} Environment key-value pairs - * `execPath` {string} Executable used to create the child process - * `execArgv` {Array} List of string arguments passed to the executable - (Default: `process.execArgv`) + * `cwd` {string} Current working directory of the child process. + * `env` {Object} Environment key-value pairs. + * `execPath` {string} Executable used to create the child process. + * `execArgv` {Array} List of string arguments passed to the executable. + **Default:** `process.execArgv` * `silent` {boolean} If `true`, stdin, stdout, and stderr of the child will be piped to the parent, otherwise they will be inherited from the parent, see the `'pipe'` and `'inherit'` options for [`child_process.spawn()`][]'s - [`stdio`][] for more details (Default: `false`) + [`stdio`][] for more details. **Default:** `false` * `stdio` {Array|string} See [`child_process.spawn()`][]'s [`stdio`][]. When this option is provided, it overrides `silent`. If the array variant is used, it must contain exactly one item with value `'ipc'` or an error will be thrown. For instance `[0, 1, 2, 'ipc']`. - * `uid` {number} Sets the user identity of the process. (See setuid(2).) - * `gid` {number} Sets the group identity of the process. (See setgid(2).) + * `uid` {number} Sets the user identity of the process (see setuid(2)). + * `gid` {number} Sets the group identity of the process (see setgid(2)). * Returns: {ChildProcess} The `child_process.fork()` method is a special case of @@ -371,24 +372,24 @@ changes: description: The `shell` option is supported now. --> -* `command` {string} The command to run -* `args` {Array} List of string arguments +* `command` {string} The command to run. +* `args` {Array} List of string arguments. * `options` {Object} - * `cwd` {string} Current working directory of the child process - * `env` {Object} Environment key-value pairs + * `cwd` {string} Current working directory of the child process. + * `env` {Object} Environment key-value pairs. * `argv0` {string} Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` if not specified. - * `stdio` {Array|string} Child's stdio configuration. (See - [`options.stdio`][`stdio`]) + * `stdio` {Array|string} Child's stdio configuration (see + [`options.stdio`][`stdio`]). * `detached` {boolean} Prepare child to run independently of its parent process. Specific behavior depends on the platform, see - [`options.detached`][]) - * `uid` {number} Sets the user identity of the process. (See setuid(2).) - * `gid` {number} Sets the group identity of the process. (See setgid(2).) + [`options.detached`][]). + * `uid` {number} Sets the user identity of the process (see setuid(2)). + * `gid` {number} Sets the group identity of the process (see setgid(2)). * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. Defaults to `false` (no shell). + [Default Windows Shell][]. **Default:** `false` (no shell). * Returns: {ChildProcess} The `child_process.spawn()` method spawns a new process using the given @@ -656,28 +657,28 @@ changes: description: The `encoding` option can now explicitly be set to `buffer`. --> -* `file` {string} The name or path of the executable file to run -* `args` {Array} List of string arguments +* `file` {string} The name or path of the executable file to run. +* `args` {string[]} List of string arguments. * `options` {Object} - * `cwd` {string} Current working directory of the child process + * `cwd` {string} Current working directory of the child process. * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin - to the spawned process + to the spawned process. - supplying this value will override `stdio[0]` - * `stdio` {string|Array} Child's stdio configuration. (Default: `'pipe'`) + * `stdio` {string|Array} Child's stdio configuration. **Default:** `'pipe'` - `stderr` by default will be output to the parent process' stderr unless `stdio` is specified - * `env` {Object} Environment key-value pairs - * `uid` {number} Sets the user identity of the process. (See setuid(2).) - * `gid` {number} Sets the group identity of the process. (See setgid(2).) + * `env` {Object} Environment key-value pairs. + * `uid` {number} Sets the user identity of the process (see setuid(2)). + * `gid` {number} Sets the group identity of the process (see setgid(2)). * `timeout` {number} In milliseconds the maximum amount of time the process - is allowed to run. (Default: `undefined`) + is allowed to run. **Default:** `undefined` * `killSignal` {string|integer} The signal value to be used when the spawned - process will be killed. (Default: `'SIGTERM'`) + process will be killed. **Default:** `'SIGTERM'` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. (Default: `200*1024`) If exceeded, the child process is terminated. + stderr. **Default:** `200*1024` If exceeded, the child process is terminated. See caveat at [`maxBuffer` and Unicode][]. - * `encoding` {string} The encoding used for all stdio inputs and outputs. (Default: `'buffer'`) -* Returns: {Buffer|string} The stdout from the command + * `encoding` {string} The encoding used for all stdio inputs and outputs. **Default:** `'buffer'` +* Returns: {Buffer|string} The stdout from the command. The `child_process.execFileSync()` method is generally identical to [`child_process.execFile()`][] with the exception that the method will not return @@ -702,31 +703,31 @@ changes: description: The `input` option can now be a `Uint8Array`. --> -* `command` {string} The command to run +* `command` {string} The command to run. * `options` {Object} - * `cwd` {string} Current working directory of the child process + * `cwd` {string} Current working directory of the child process. * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin - to the spawned process - - supplying this value will override `stdio[0]` - * `stdio` {string|Array} Child's stdio configuration. (Default: `'pipe'`) + to the spawned process. + - supplying this value will override `stdio[0]`. + * `stdio` {string|Array} Child's stdio configuration. **Default:** `'pipe'` - `stderr` by default will be output to the parent process' stderr unless `stdio` is specified - * `env` {Object} Environment key-value pairs - * `shell` {string} Shell to execute the command with - (Default: `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See - [Shell Requirements][] and [Default Windows Shell][].) - * `uid` {number} Sets the user identity of the process. (See setuid(2).) - * `gid` {number} Sets the group identity of the process. (See setgid(2).) + * `env` {Object} Environment key-value pairs. + * `shell` {string} Shell to execute the command with. + **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See + [Shell Requirements][] and [Default Windows Shell][]. + * `uid` {number} Sets the user identity of the process. (See setuid(2)). + * `gid` {number} Sets the group identity of the process. (See setgid(2)). * `timeout` {number} In milliseconds the maximum amount of time the process - is allowed to run. (Default: `undefined`) + is allowed to run. **Default:** `undefined` * `killSignal` {string|integer} The signal value to be used when the spawned - process will be killed. (Default: `'SIGTERM'`) + process will be killed. **Default:** `'SIGTERM'` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. (Default: `200*1024`) If exceeded, the child process is terminated. + stderr. **Default:** `200*1024` If exceeded, the child process is terminated. See caveat at [`maxBuffer` and Unicode][]. * `encoding` {string} The encoding used for all stdio inputs and outputs. - (Default: `'buffer'`) -* Returns: {Buffer|string} The stdout from the command + **Default:** `'buffer'` +* Returns: {Buffer|string} The stdout from the command. The `child_process.execSync()` method is generally identical to [`child_process.exec()`][] with the exception that the method will not return until @@ -759,38 +760,38 @@ changes: description: The `shell` option is supported now. --> -* `command` {string} The command to run -* `args` {Array} List of string arguments +* `command` {string} The command to run. +* `args` {Array} List of string arguments. * `options` {Object} - * `cwd` {string} Current working directory of the child process + * `cwd` {string} Current working directory of the child process. * `input` {string|Buffer|Uint8Array} The value which will be passed as stdin - to the spawned process - - supplying this value will override `stdio[0]` + to the spawned process. + - supplying this value will override `stdio[0]`. * `stdio` {string|Array} Child's stdio configuration. - * `env` {Object} Environment key-value pairs - * `uid` {number} Sets the user identity of the process. (See setuid(2).) - * `gid` {number} Sets the group identity of the process. (See setgid(2).) + * `env` {Object} Environment key-value pairs. + * `uid` {number} Sets the user identity of the process (see setuid(2)). + * `gid` {number} Sets the group identity of the process (see setgid(2)). * `timeout` {number} In milliseconds the maximum amount of time the process - is allowed to run. (Default: `undefined`) + is allowed to run. **Default:** `undefined` * `killSignal` {string|integer} The signal value to be used when the spawned - process will be killed. (Default: `'SIGTERM'`) + process will be killed. **Default:** `'SIGTERM'` * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or - stderr. (Default: `200*1024`) If exceeded, the child process is terminated. + stderr. **Default:** `200*1024` If exceeded, the child process is terminated. See caveat at [`maxBuffer` and Unicode][]. * `encoding` {string} The encoding used for all stdio inputs and outputs. - (Default: `'buffer'`) + **Default:** `'buffer'` * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different shell can be specified as a string. See [Shell Requirements][] and - [Default Windows Shell][]. Defaults to `false` (no shell). + [Default Windows Shell][]. **Default:** `false` (no shell). * Returns: {Object} - * `pid` {number} Pid of the child process - * `output` {Array} Array of results from stdio output - * `stdout` {Buffer|string} The contents of `output[1]` - * `stderr` {Buffer|string} The contents of `output[2]` - * `status` {number} The exit code of the child process - * `signal` {string} The signal used to kill the child process - * `error` {Error} The error object if the child process failed or timed out + * `pid` {number} Pid of the child process. + * `output` {Array} Array of results from stdio output. + * `stdout` {Buffer|string} The contents of `output[1]`. + * `stderr` {Buffer|string} The contents of `output[2]`. + * `status` {number} The exit code of the child process. + * `signal` {string} The signal used to kill the child process. + * `error` {Error} The error object if the child process failed or timed out. The `child_process.spawnSync()` method is generally identical to [`child_process.spawn()`][] with the exception that the function will not return @@ -822,8 +823,8 @@ instances of `ChildProcess`. added: v0.7.7 --> -* `code` {number} the exit code if the child exited on its own. -* `signal` {string} the signal by which the child process was terminated. +* `code` {number} The exit code if the child exited on its own. +* `signal` {string} The signal by which the child process was terminated. The `'close'` event is emitted when the stdio streams of a child process have been closed. This is distinct from the [`'exit'`][] event, since multiple @@ -842,7 +843,7 @@ property is `false`. ### Event: 'error' -* `err` {Error} the error. +* `err` {Error} The error. The `'error'` event is emitted whenever: @@ -861,8 +862,8 @@ See also [`subprocess.kill()`][] and [`subprocess.send()`][]. added: v0.1.90 --> -* `code` {number} the exit code if the child exited on its own. -* `signal` {string} the signal by which the child process was terminated. +* `code` {number} The exit code if the child exited on its own. +* `signal` {string} The signal by which the child process was terminated. The `'exit'` event is emitted after the child process ends. If the process exited, `code` is the final exit code of the process, otherwise `null`. If the @@ -884,8 +885,8 @@ See waitpid(2). added: v0.5.9 --> -* `message` {Object} a parsed JSON object or primitive value. -* `sendHandle` {Handle} a [`net.Socket`][] or [`net.Server`][] object, or +* `message` {Object} A parsed JSON object or primitive value. +* `sendHandle` {Handle} A [`net.Socket`][] or [`net.Server`][] object, or undefined. The `'message'` event is triggered when a child process uses [`process.send()`][] @@ -910,7 +911,7 @@ no IPC channel currently exists, this property is `undefined`. added: v0.7.2 --> -* {boolean} Set to `false` after `subprocess.disconnect()` is called +* {boolean} Set to `false` after `subprocess.disconnect()` is called. The `subprocess.connected` property indicates whether it is still possible to send and receive messages from a child process. When `subprocess.connected` is diff --git a/doc/api/cluster.md b/doc/api/cluster.md index cce0f8479b..4e2b4eab88 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -147,8 +147,8 @@ Within a worker, `process.on('error')` may also be used. added: v0.11.2 --> -* `code` {number} the exit code, if it exited normally. -* `signal` {string} the name of the signal (e.g. `'SIGHUP'`) that caused +* `code` {number} The exit code, if it exited normally. +* `signal` {string} The name of the signal (e.g. `'SIGHUP'`) that caused the process to be killed. Similar to the `cluster.on('exit')` event, but specific to this worker. @@ -429,7 +429,7 @@ changes: * `message` {Object} * `sendHandle` {Handle} * `callback` {Function} -* Returns: Boolean +* Returns: {boolean} Send a message to a worker or master, optionally with a handle. @@ -480,8 +480,8 @@ added: v0.7.9 --> * `worker` {cluster.Worker} -* `code` {number} the exit code, if it exited normally. -* `signal` {string} the name of the signal (e.g. `'SIGHUP'`) that caused +* `code` {number} The exit code, if it exited normally. +* `signal` {string} The name of the signal (e.g. `'SIGHUP'`) that caused the process to be killed. When any of the workers die the cluster module will emit the `'exit'` event. @@ -630,8 +630,8 @@ If accuracy is important, use `cluster.settings`. added: v0.7.7 --> -* `callback` {Function} called when all workers are disconnected and handles are - closed +* `callback` {Function} Called when all workers are disconnected and handles are + closed. Calls `.disconnect()` on each worker in `cluster.workers`. @@ -648,7 +648,7 @@ added: v0.6.0 --> * `env` {Object} Key/value pairs to add to worker process environment. -* return {cluster.Worker} +* Returns: {cluster.Worker} Spawn a new worker process. @@ -709,9 +709,9 @@ changes: executable. (Default=`process.execArgv`) * `exec` {string} File path to worker file. (Default=`process.argv[1]`) * `args` {Array} String arguments passed to worker. - (Default=`process.argv.slice(2)`) + **Default:** `process.argv.slice(2)` * `silent` {boolean} Whether or not to send output to parent's stdio. - (Default=`false`) + **Default:** `false` * `stdio` {Array} Configures the stdio of forked processes. Because the cluster module relies on IPC to function, this configuration must contain an `'ipc'` entry. When this option is provided, it overrides `silent`. diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 0e39e53d4f..69f88f58cb 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -74,12 +74,12 @@ added: v0.1.99 The `'message'` event is emitted when a new datagram is available on a socket. The event handler function is passed two arguments: `msg` and `rinfo`. -* `msg` {Buffer} - The message -* `rinfo` {Object} - Remote address information - * `address` {string} The sender address - * `family` {string} The address family (`'IPv4'` or `'IPv6'`) - * `port` {number} The sender port - * `size` {number} The message size +* `msg` {Buffer} The message. +* `rinfo` {Object} Remote address information. + * `address` {string} The sender address. + * `family` {string} The address family (`'IPv4'` or `'IPv6'`). + * `port` {number} The sender port. + * `size` {number} The message size. ### socket.addMembership(multicastAddress[, multicastInterface]) <!-- YAML @@ -87,7 +87,7 @@ added: v0.6.9 --> * `multicastAddress` {string} -* `multicastInterface` {string}, Optional +* `multicastInterface` {string} Tells the kernel to join a multicast group at the given `multicastAddress` and `multicastInterface` using the `IP_ADD_MEMBERSHIP` socket option. If the @@ -109,10 +109,9 @@ properties. added: v0.1.99 --> -* `port` {number} - Integer, Optional -* `address` {string}, Optional -* `callback` {Function} with no parameters, Optional. Called when - binding is complete. +* `port` {number} Integer. +* `address` {string} +* `callback` {Function} with no parameters. Called when binding is complete. For UDP sockets, causes the `dgram.Socket` to listen for datagram messages on a named `port` and optional `address`. If `port` is not @@ -161,11 +160,11 @@ server.bind(41234); added: v0.11.14 --> -* `options` {Object} - Required. Supports the following properties: - * `port` {number} - Optional. - * `address` {string} - Optional. - * `exclusive` {boolean} - Optional. -* `callback` {Function} - Optional. +* `options` {Object} Required. Supports the following properties: + * `port` {Integer} + * `address` {string} + * `exclusive` {boolean} +* `callback` {Function} For UDP sockets, causes the `dgram.Socket` to listen for datagram messages on a named `port` and optional `address` that are passed as @@ -217,7 +216,7 @@ added: v0.6.9 --> * `multicastAddress` {string} -* `multicastInterface` {string}, Optional +* `multicastInterface` {string} Instructs the kernel to leave a multicast group at `multicastAddress` using the `IP_DROP_MEMBERSHIP` socket option. This method is automatically called by the @@ -277,12 +276,12 @@ changes: and `length` parameters are optional now. --> -* `msg` {Buffer|Uint8Array|string|array} Message to be sent -* `offset` {number} Integer. Optional. Offset in the buffer where the message starts. -* `length` {number} Integer. Optional. Number of bytes in the message. +* `msg` {Buffer|Uint8Array|string|Array} Message to be sent. +* `offset` {number} Integer. Offset in the buffer where the message starts. +* `length` {number} Integer. Number of bytes in the message. * `port` {number} Integer. Destination port. -* `address` {string} Destination hostname or IP address. Optional. -* `callback` {Function} Called when the message has been sent. Optional. +* `address` {string} Destination hostname or IP address. +* `callback` {Function} Called when the message has been sent. Broadcasts a datagram on the socket. The destination `port` and `address` must be specified. @@ -479,7 +478,7 @@ multicast packets will also be received on the local interface. added: v0.3.8 --> -* `ttl` {number} Integer +* `ttl` {number} Integer. Sets the `IP_MULTICAST_TTL` socket option. While TTL generally stands for "Time to Live", in this context it specifies the number of IP hops that a @@ -515,7 +514,7 @@ in bytes. added: v0.1.101 --> -* `ttl` {number} Integer +* `ttl` {number} Integer. Sets the `IP_TTL` socket option. While TTL generally stands for "Time to Live", in this context it specifies the number of IP hops that a packet is allowed to @@ -583,12 +582,11 @@ changes: * `type` {string} The family of socket. Must be either `'udp4'` or `'udp6'`. Required. * `reuseAddr` {boolean} When `true` [`socket.bind()`][] will reuse the - address, even if another process has already bound a socket on it. Optional. + address, even if another process has already bound a socket on it. Defaults to `false`. - * `recvBufferSize` {number} - Optional. Sets the `SO_RCVBUF` socket value. - * `sendBufferSize` {number} - Optional. 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. Defaults to [`dns.lookup()`][]. - Optional. * `callback` {Function} Attached as a listener for `'message'` events. Optional. * Returns: {dgram.Socket} @@ -605,9 +603,8 @@ and port can be retrieved using [`socket.address().address`][] and added: v0.1.99 --> -* `type` {string} - Either 'udp4' or 'udp6' +* `type` {string} - Either 'udp4' or 'udp6'. * `callback` {Function} - Attached as a listener to `'message'` events. - Optional * Returns: {dgram.Socket} Creates a `dgram.Socket` object of the specified `type`. The `type` argument diff --git a/doc/api/net.md b/doc/api/net.md index f1979d298a..57cb410e52 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -164,7 +164,7 @@ connections use asynchronous [`server.getConnections()`][] instead. added: v0.9.7 --> -* Returns {net.Server} +* Returns: {net.Server} Asynchronously get the number of concurrent connections on the server. Works when sockets were sent to forks. diff --git a/doc/api/stream.md b/doc/api/stream.md index 8aaa4ff2e6..8a758d75f3 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1624,7 +1624,7 @@ changes: any JavaScript value. * `encoding` {string} Encoding of string chunks. Must be a valid Buffer encoding, such as `'utf8'` or `'ascii'` -* Returns {boolean} `true` if additional chunks of data may continued to be +* Returns: {boolean} `true` if additional chunks of data may continued to be pushed; `false` otherwise. When `chunk` is a `Buffer`, `Uint8Array` or `string`, the `chunk` of data will |