From 9baea3b238c83e51067e1d5fbb093b5d11a9a71c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Kraj=C4=8Dovi=C4=8D?= Date: Fri, 27 Oct 2017 21:51:28 +0200 Subject: [PATCH] doc: make default values and periods consistent PR-URL: https://github.com/nodejs/node/pull/16563 Reviewed-By: Jeremiah Senkpiel Reviewed-By: Gibson Fahnestock Reviewed-By: Gireesh Punathil Reviewed-By: Colin Ihrig Reviewed-By: James M Snell --- doc/api/cluster.md | 4 +-- doc/api/dns.md | 6 ++--- doc/api/http2.md | 64 ++++++++++++++++++++++----------------------- doc/api/net.md | 40 ++++++++++++++-------------- doc/api/os.md | 2 +- doc/api/readline.md | 21 +++++++-------- 6 files changed, 68 insertions(+), 69 deletions(-) diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 236d461736..3ceec142b6 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -706,8 +706,8 @@ changes: * {Object} * `execArgv` {Array} List of string arguments passed to the Node.js - executable. (Default=`process.execArgv`) - * `exec` {string} File path to worker file. (Default=`process.argv[1]`) + 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)` * `silent` {boolean} Whether or not to send output to parent's stdio. diff --git a/doc/api/dns.md b/doc/api/dns.md index 56f2d0660c..0b064ff79d 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -141,11 +141,11 @@ changes: - `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple flags may be passed by bitwise `OR`ing their values. - `all` {boolean} When `true`, the callback returns all resolved addresses in - an array. Otherwise, returns a single address. Defaults to `false`. + an array. Otherwise, returns a single address. **Default:** `false` - `verbatim` {boolean} When `true`, the callback receives IPv4 and IPv6 addresses in the order the DNS resolver returned them. When `false`, IPv4 addresses are placed before IPv6 addresses. - Default: currently `false` (addresses are reordered) but this is expected + **Default:** currently `false` (addresses are reordered) but this is expected to change in the not too distant future. New code should use `{ verbatim: true }`. - `callback` {Function} @@ -245,7 +245,7 @@ Promise for an object with `hostname` and `service` properties. added: v0.1.27 --> - `hostname` {string} Hostname to resolve. -- `rrtype` {string} Resource record type. Default: `'A'`. +- `rrtype` {string} Resource record type. **Default:** `'A'` - `callback` {Function} - `err` {Error} - `records` {string[] | Object[] | Object} diff --git a/doc/api/http2.md b/doc/api/http2.md index fe78187068..2a958c30c3 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -365,7 +365,7 @@ added: v8.4.0 * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, the created stream is made the sole direct dependency of the parent, with all other existing dependents made a dependent of the newly created stream. - Defaults to `false`. + **Default:** `false` * `parent` {number} Specifies the numeric identifier of a stream the newly created stream is dependent on. * `weight` {number} Specifies the relative dependency of a stream in relation @@ -415,7 +415,7 @@ added: v8.4.0 --> * stream {Http2Stream} -* code {number} Unsigned 32-bit integer identifying the error code. Defaults to +* code {number} Unsigned 32-bit integer identifying the error code. **Default:** `http2.constant.NGHTTP2_NO_ERROR` (`0x00`) * Returns: {undefined} @@ -444,7 +444,7 @@ added: v8.4.0 * `graceful` {boolean} `true` to attempt a polite shutdown of the `Http2Session`. * `errorCode` {number} The HTTP/2 [error code][] to return. Note that this is - *not* the same thing as an HTTP Response Status Code. Defaults to `0x00` + *not* the same thing as an HTTP Response Status Code. **Default:** `0x00` (No Error). * `lastStreamID` {number} The Stream ID of the last successfully processed `Http2Stream` on this `Http2Session`. @@ -522,8 +522,8 @@ added: v8.4.0 * `options` {Object} * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, the given stream is made the sole direct dependency of the parent, with - all other existing dependents made a dependent of the given stream. Defaults - to `false`. + all other existing dependents made a dependent of the given stream. **Default:** + `false` * `parent` {number} Specifies the numeric identifier of a stream the given stream is dependent on. * `weight` {number} Specifies the relative dependency of a stream in relation @@ -734,8 +734,8 @@ added: v8.4.0 * `options` {Object} * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, this stream is made the sole direct dependency of the parent, with - all other existing dependents made a dependent of this stream. Defaults - to `false`. + all other existing dependents made a dependent of this stream. **Default:** + `false` * `parent` {number} Specifies the numeric identifier of a stream this stream is dependent on. * `weight` {number} Specifies the relative dependency of a stream in relation @@ -764,7 +764,7 @@ calling `http2stream.rstStream()`, or `http2stream.destroy()`. Will be added: v8.4.0 --> -* code {number} Unsigned 32-bit integer identifying the error code. Defaults to +* code {number} Unsigned 32-bit integer identifying the error code. **Default:** `http2.constant.NGHTTP2_NO_ERROR` (`0x00`) * Returns: {undefined} @@ -986,7 +986,7 @@ added: v8.4.0 * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, the created stream is made the sole direct dependency of the parent, with all other existing dependents made a dependent of the newly created stream. - Defaults to `false`. + **Default:** `false` * `parent` {number} Specifies the numeric identifier of a stream the newly created stream is dependent on. * `callback` {Function} Callback that is called once the push stream has been @@ -1063,14 +1063,14 @@ fields. added: v8.4.0 --> -* `fd` {number} A readable file descriptor +* `fd` {number} A readable file descriptor. * `headers` {[Headers Object][]} * `options` {Object} * `statCheck` {Function} * `getTrailers` {Function} Callback function invoked to collect trailer headers. - * `offset` {number} The offset position at which to begin reading - * `length` {number} The amount of data from the fd to send + * `offset` {number} The offset position at which to begin reading. + * `length` {number} The amount of data from the fd to send. Initiates a response whose data is read from the given file descriptor. No validation is performed on the given file descriptor. If an error occurs while @@ -1152,11 +1152,11 @@ added: v8.4.0 * `options` {Object} * `statCheck` {Function} * `onError` {Function} Callback function invoked in the case of an - Error before send + Error before send. * `getTrailers` {Function} Callback function invoked to collect trailer headers. - * `offset` {number} The offset position at which to begin reading - * `length` {number} The amount of data from the fd to send + * `offset` {number} The offset position at which to begin reading. + * `length` {number} The amount of data from the fd to send. Sends a regular file as the response. The `path` must specify a regular file or an `'error'` event will be emitted on the `Http2Stream` object. @@ -1474,13 +1474,13 @@ added: v8.4.0 * `options` {Object} * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size - for deflating header fields. Defaults to 4Kib. + for deflating header fields. **Default:** `4Kib` * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a 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. Defaults to + 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. @@ -1492,8 +1492,8 @@ added: v8.4.0 amount of padding. * `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 - `maxConcurrentStreams`. Defaults to 100. + be overridden if the remote peer sets its own value for. + `maxConcurrentStreams`. **Default** `100` * `selectPadding` {Function} When `options.paddingStrategy` is equal to `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function used to determine the padding. See [Using options.selectPadding][]. @@ -1529,16 +1529,16 @@ added: v8.4.0 * `options` {Object} * `allowHTTP1` {boolean} Incoming client connections that do not support - HTTP/2 will be downgraded to HTTP/1.x when set to `true`. The default value - is `false`. See the [`'unknownProtocol'`][] event. See [ALPN negotiation][]. + HTTP/2 will be downgraded to HTTP/1.x when set to `true`. **Default:** + `false`. See the [`'unknownProtocol'`][] event. See [ALPN negotiation][]. * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size - for deflating header fields. Defaults to 4Kib. + for deflating header fields. **Default:** `4Kib` * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a 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. Defaults to + 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. @@ -1551,7 +1551,7 @@ added: v8.4.0 * `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 - `maxConcurrentStreams`. Defaults to 100. + `maxConcurrentStreams`. **Default:** `100` * `selectPadding` {Function} When `options.paddingStrategy` is equal to `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function used to determine the padding. See [Using options.selectPadding][]. @@ -1595,7 +1595,7 @@ added: v8.4.0 * `authority` {string|URL} * `options` {Object} * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size - for deflating header fields. Defaults to 4Kib. + for deflating header fields. **Default:** `4Kib` * `maxReservedRemoteStreams` {number} Sets the maximum number of reserved push streams the client will accept at any given time. Once the current number of currently reserved push streams exceeds reaches this limit, new push streams @@ -1605,7 +1605,7 @@ added: v8.4.0 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. Defaults to + 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. @@ -1618,7 +1618,7 @@ added: v8.4.0 * `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 - `maxConcurrentStreams`. Defaults to 100. + `maxConcurrentStreams`. **Default:** `100` * `selectPadding` {Function} When `options.paddingStrategy` is equal to `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function used to determine the padding. See [Using options.selectPadding][]. @@ -1707,7 +1707,7 @@ console.log(packed.toString('base64')); added: v8.4.0 --> -* `buf` {Buffer|Uint8Array} The packed settings +* `buf` {Buffer|Uint8Array} The packed settings. * Returns: {[Settings Object][]} Returns a [Settings Object][] containing the deserialized settings from the @@ -1757,15 +1757,15 @@ These objects are ordinary JavaScript objects containing the following properties. * `headerTableSize` {number} Specifies the maximum number of bytes used for - header compression. The default value is 4,096 octets. The minimum allowed + header compression. **Default:** `4,096 octets`. The minimum allowed value is 0. The maximum allowed value is 232-1. * `enablePush` {boolean} Specifies `true` if HTTP/2 Push Streams are to be permitted on the `Http2Session` instances. * `initialWindowSize` {number} Specifies the *senders* initial window size - for stream-level flow control. The default value is 65,535 bytes. The minimum + for stream-level flow control. **Default:** `65,535 bytes`. The minimum allowed value is 0. The maximum allowed value is 232-1. * `maxFrameSize` {number} Specifies the size of the largest frame payload. - The default and the minimum allowed value is 16,384 bytes. The maximum + **Default:** `16,384 bytes`. The minimum allowed value is 16,384. The maximum allowed value is 224-1. * `maxConcurrentStreams` {number} Specifies the maximum number of concurrent streams permitted on an `Http2Session`. There is no default value which @@ -2478,7 +2478,7 @@ added: v8.4.0 --> * `name` {string} -* `value` {string | string[]} +* `value` {string|string[]} Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings diff --git a/doc/api/net.md b/doc/api/net.md index 57cb410e52..04821ad2e9 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -250,10 +250,10 @@ added: v0.11.14 * `path` {string} Will be ignored if `port` is specified. See [Identifying paths for IPC connections][]. * `backlog` {number} Common parameter of [`server.listen()`][] - functions - * `exclusive` {boolean} Default to `false` + functions. + * `exclusive` {boolean} **Default:** `false` * `callback` {Function} Common parameter of [`server.listen()`][] - functions + functions. * Returns: {net.Server} If `port` is specified, it behaves the same as @@ -283,8 +283,8 @@ added: v0.1.90 * `path` {String} Path the server should listen to. See [Identifying paths for IPC connections][]. -* `backlog` {number} Common parameter of [`server.listen()`][] functions -* `callback` {Function} Common parameter of [`server.listen()`][] functions +* `backlog` {number} Common parameter of [`server.listen()`][] functions. +* `callback` {Function} Common parameter of [`server.listen()`][] functions. * Returns: {net.Server} Start a [IPC][] server listening for connections on the given `path`. @@ -295,8 +295,8 @@ added: v0.1.90 --> * `port` {number} * `host` {string} -* `backlog` {number} Common parameter of [`server.listen()`][] functions -* `callback` {Function} Common parameter of [`server.listen()`][] functions +* `backlog` {number} Common parameter of [`server.listen()`][] functions. +* `callback` {Function} Common parameter of [`server.listen()`][] functions. * Returns: {net.Server} Start a TCP server listening for connections on the given `port` and `host`. @@ -385,11 +385,11 @@ Creates a new socket object. the given file descriptor, otherwise a new socket will be created. * `allowHalfOpen` {boolean} Indicates whether half-opened TCP connections are allowed. See [`net.createServer()`][] and the [`'end'`][] event - for details. Defaults to `false`. + for details. **Default:** `false` * `readable` {boolean} Allow reads on the socket when an `fd` is passed, - otherwise ignored. Defaults to `false`. + otherwise ignored. **Default:** `false` * `writable` {boolean} Allow writes on the socket when an `fd` is passed, - otherwise ignored. Defaults to `false`. + otherwise ignored. **Default:** `false` * Returns: {net.Socket} The newly created socket can be either a TCP socket or a streaming [IPC][] @@ -581,12 +581,12 @@ this only when implementing a custom Socket. For TCP connections, available `options` are: * `port` {number} Required. Port the socket should connect to. -* `host` {string} Host the socket should connect to. Defaults to `'localhost'`. +* `host` {string} Host the socket should connect to. **Default:** `'localhost'` * `localAddress` {string} Local address the socket should connect from. * `localPort` {number} Local port the socket should connect from. -* `family` {number}: Version of IP stack, can be either 4 or 6. Defaults to 4. +* `family` {number}: Version of IP stack, can be either 4 or 6. **Default:** `4` * `hints` {number} Optional [`dns.lookup()` hints][]. -* `lookup` {Function} Custom lookup function. Defaults to [`dns.lookup()`][]. +* `lookup` {Function} Custom lookup function. **Default:** [`dns.lookup()`][] For [IPC][] connections, available `options` are: @@ -965,9 +965,9 @@ added: v0.1.90 * `port` {number} Port the socket should connect to. Will be passed to [`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`]. -* `host` {string} Host the socket should connect to. Defaults to `'localhost'`. - Will be passed to +* `host` {string} Host the socket should connect to. Will be passed to [`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`]. + **Default:** `'localhost'` * `connectListener` {Function} Common parameter of the [`net.createConnection()`][] functions, an "once" listener for the `'connect'` event on the initiating socket. Will be passed to @@ -989,12 +989,12 @@ added: v0.5.0 Creates a new TCP or [IPC][] server. * `options` {Object} - * `allowHalfOpen` {boolean} Default to `false`. Indicates whether half-opened - TCP connections are allowed. - * `pauseOnConnect` {boolean} Default to `false`. Indicates whether the socket - should be paused on incoming connections. + * `allowHalfOpen` {boolean} Indicates whether half-opened TCP + connections are allowed. **Default:** `false` + * `pauseOnConnect` {boolean} Indicates whether the socket should be + paused on incoming connections. **Default:** `false` * `connectionListener` {Function} Automatically set as a listener for the - [`'connection'`][] event + [`'connection'`][] event. * Returns: {net.Server} If `allowHalfOpen` is set to `true`, when the other end of the socket diff --git a/doc/api/os.md b/doc/api/os.md index 019330cdf9..dca9b266f7 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -401,7 +401,7 @@ added: v6.0.0 * `options` {Object} * `encoding` {string} Character encoding used to interpret resulting strings. If `encoding` is set to `'buffer'`, the `username`, `shell`, and `homedir` - values will be `Buffer` instances. (Default: 'utf8') + values will be `Buffer` instances. **Default:** `'utf8'` * Returns: {Object} The `os.userInfo()` method returns information about the currently effective diff --git a/doc/api/readline.md b/doc/api/readline.md index 353ef87f8f..8619d75132 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -369,21 +369,20 @@ changes: * `terminal` {boolean} `true` if the `input` and `output` streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. Defaults to checking `isTTY` on the `output` stream upon instantiation. - * `historySize` {number} maximum number of history lines retained. To disable - the history set this value to `0`. Defaults to `30`. This option makes sense - only if `terminal` is set to `true` by the user or by an internal `output` - check, otherwise the history caching mechanism is not initialized at all. - * `prompt` - the prompt string to use. Default: `'> '` + * `historySize` {number} Maximum number of history lines retained. To disable + the history set this value to `0`. This option makes sense only if `terminal` + is set to `true` by the user or by an internal `output` check, otherwise the + history caching mechanism is not initialized at all. **Default:** `30` + * `prompt` {string} The prompt string to use. **Default:** `'> '` * `crlfDelay` {number} If the delay between `\r` and `\n` exceeds `crlfDelay` milliseconds, both `\r` and `\n` will be treated as separate - end-of-line input. Default to `100` milliseconds. - `crlfDelay` will be coerced to a number no less than `100`. It can be set to - `Infinity`, in which case `\r` followed by `\n` will always be considered a - single newline (which may be reasonable for [reading files][] with `\r\n` - line delimiter). + end-of-line input. `crlfDelay` will be coerced to a number no less than `100`. + It can be set to `Infinity`, in which case `\r` followed by `\n` will always be + considered a single newline (which may be reasonable for [reading files][] + with `\r\n` line delimiter). **Default:** `100` * `removeHistoryDuplicates` {boolean} If `true`, when a new input line added to the history list duplicates an older one, this removes the older line - from the list. Defaults to `false`. + from the list. **Default:** `false` The `readline.createInterface()` method creates a new `readline.Interface` instance.