From b01fd8ce3a76cb0d917e48e8cec8565341180b0e Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Mon, 13 Feb 2017 04:49:35 +0200 Subject: [PATCH] doc: fix sorting in API references PR-URL: https://github.com/nodejs/node/pull/11529 Backport-Of: https://github.com/nodejs/node/pull/11331 Reviewed-By: James M Snell Reviewed-By: Sam Roberts --- doc/api/buffer.md | 192 ++++++++++++++++++++++----------------------- doc/api/crypto.md | 32 ++++---- doc/api/dgram.md | 32 ++++---- doc/api/dns.md | 18 ++--- doc/api/domain.md | 152 +++++++++++++++++------------------ doc/api/fs.md | 36 ++++----- doc/api/http.md | 24 +++--- doc/api/process.md | 154 ++++++++++++++++++------------------ doc/api/tls.md | 100 +++++++++++------------ doc/api/url.md | 84 ++++++++++---------- doc/api/util.md | 42 +++++----- doc/api/v8.md | 78 +++++++++--------- 12 files changed, 472 insertions(+), 472 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index ace16159a64a9f..983d2bbe453c57 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -313,32 +313,6 @@ Example: const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); ``` -### new Buffer(buffer) - - -> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead. - -* `buffer` {Buffer} An existing `Buffer` to copy data from - -Copies the passed `buffer` data onto a new `Buffer` instance. - -Example: - -```js -const buf1 = new Buffer('buffer'); -const buf2 = new Buffer(buf1); - -buf1[0] = 0x61; - -// Prints: auffer -console.log(buf1.toString()); - -// Prints: buffer -console.log(buf2.toString()); -``` - ### new Buffer(arrayBuffer[, byteOffset [, length]]) + +> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead. + +* `buffer` {Buffer} An existing `Buffer` to copy data from + +Copies the passed `buffer` data onto a new `Buffer` instance. + +Example: + +```js +const buf1 = new Buffer('buffer'); +const buf2 = new Buffer(buf1); + +buf1[0] = 0x61; + +// Prints: auffer +console.log(buf1.toString()); + +// Prints: buffer +console.log(buf2.toString()); +``` + ### new Buffer(size) + +* `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 + +Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`]. + +Examples: + +```js +const buf = Buffer.from('this is a buffer'); + +// Prints: true +console.log(buf.includes('this')); + +// Prints: true +console.log(buf.includes('is')); + +// Prints: true +console.log(buf.includes(Buffer.from('a buffer'))); + +// Prints: true +// (97 is the decimal ASCII value for 'a') +console.log(buf.includes(97)); + +// Prints: false +console.log(buf.includes(Buffer.from('a buffer example'))); + +// Prints: true +console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8))); + +// Prints: false +console.log(buf.includes('this', 4)); +``` + ### buf.indexOf(value[, byteOffset][, encoding]) - -* `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 - -Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`]. - -Examples: - -```js -const buf = Buffer.from('this is a buffer'); - -// Prints: true -console.log(buf.includes('this')); - -// Prints: true -console.log(buf.includes('is')); - -// Prints: true -console.log(buf.includes(Buffer.from('a buffer'))); - -// Prints: true -// (97 is the decimal ASCII value for 'a') -console.log(buf.includes(97)); - -// Prints: false -console.log(buf.includes(Buffer.from('a buffer example'))); - -// Prints: true -console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8))); - -// Prints: false -console.log(buf.includes('this', 4)); -``` - ### buf.keys() + +* Returns: {Object} + +Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls +this function when stringifying a `Buffer` instance. + +Example: + +```js +const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]); +const json = JSON.stringify(buf); + +// Prints: {"type":"Buffer","data":[1,2,3,4,5]} +console.log(json); + +const copy = JSON.parse(json, (key, value) => { + return value && value.type === 'Buffer' + ? Buffer.from(value.data) + : value; +}); + +// Prints: +console.log(copy); +``` + ### buf.toString([encoding[, start[, end]]]) - -* Returns: {Object} - -Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls -this function when stringifying a `Buffer` instance. - -Example: - -```js -const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]); -const json = JSON.stringify(buf); - -// Prints: {"type":"Buffer","data":[1,2,3,4,5]} -console.log(json); - -const copy = JSON.parse(json, (key, value) => { - return value && value.type === 'Buffer' - ? Buffer.from(value.data) - : value; -}); - -// Prints: -console.log(copy); -``` - ### buf.values() - -Returns true if `a` is equal to `b`, without leaking timing information that -would allow an attacker to guess one of the values. This is suitable for -comparing HMAC digests or secret values like authentication cookies or -[capability urls](https://www.w3.org/TR/capability-urls/). - -`a` and `b` must both be `Buffer`s, and they must have the same length. - -**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the -*surrounding* code is timing-safe. Care should be taken to ensure that the -surrounding code does not introduce timing vulnerabilities. - ### crypto.privateEncrypt(private_key, buffer) + +Returns true if `a` is equal to `b`, without leaking timing information that +would allow an attacker to guess one of the values. This is suitable for +comparing HMAC digests or secret values like authentication cookies or +[capability urls](https://www.w3.org/TR/capability-urls/). + +`a` and `b` must both be `Buffer`s, and they must have the same length. + +**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the +*surrounding* code is timing-safe. Care should be taken to ensure that the +surrounding code does not introduce timing vulnerabilities. + ## Notes ### Legacy Streams API (pre Node.js v0.10) diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 91db049fd1ad75..b763620f2c58e2 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -225,6 +225,22 @@ never have reason to call this. If `multicastInterface` is not specified, the operating system will attempt to drop membership on all valid interfaces. +### socket.ref() + + +By default, binding a socket will cause it to block the Node.js process from +exiting as long as the socket is open. The `socket.unref()` method can be used +to exclude the socket from the reference counting that keeps the Node.js +process active. The `socket.ref()` method adds the socket back to the reference +counting and restores the default behavior. + +Calling `socket.ref()` multiples times will have no additional effect. + +The `socket.ref()` method returns a reference to the socket so calls can be +chained. + ### socket.send(msg, [offset, length,] port, address[, callback]) - -By default, binding a socket will cause it to block the Node.js process from -exiting as long as the socket is open. The `socket.unref()` method can be used -to exclude the socket from the reference counting that keeps the Node.js -process active. The `socket.ref()` method adds the socket back to the reference -counting and restores the default behavior. - -Calling `socket.ref()` multiples times will have no additional effect. - -The `socket.ref()` method returns a reference to the socket so calls can be -chained. - ### socket.unref() + +Uses the DNS protocol to resolve pointer records (`PTR` records) for the +`hostname`. The `addresses` argument passed to the `callback` function will +be an array of strings containing the reply records. + ## dns.resolveSoa(hostname, callback) - -Uses the DNS protocol to resolve pointer records (`PTR` records) for the -`hostname`. The `addresses` argument passed to the `callback` function will -be an array of strings containing the reply records. - ## dns.resolveTxt(hostname, callback) -* `fd` {Integer} Integer file descriptor used by the ReadStream. - -Emitted when the ReadStream's file is opened. +Emitted when the `ReadStream`'s underlying file descriptor has been closed +using the `fs.close()` method. -### Event: 'close' +### Event: 'open' -Emitted when the `ReadStream`'s underlying file descriptor has been closed -using the `fs.close()` method. +* `fd` {Integer} Integer file descriptor used by the ReadStream. + +Emitted when the ReadStream's file is opened. ### readStream.bytesRead -* `fd` {Integer} Integer file descriptor used by the WriteStream. - -Emitted when the WriteStream's file is opened. +Emitted when the `WriteStream`'s underlying file descriptor has been closed +using the `fs.close()` method. -### Event: 'close' +### Event: 'open' -Emitted when the `WriteStream`'s underlying file descriptor has been closed -using the `fs.close()` method. +* `fd` {Integer} Integer file descriptor used by the WriteStream. + +Emitted when the WriteStream's file is opened. ### writeStream.bytesWritten + +* {net.Socket} + +The [`net.Socket`][] object associated with the connection. + +With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the +client's authentication details. + ### message.statusCode - -* {net.Socket} - -The [`net.Socket`][] object associated with the connection. - -With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the -client's authentication details. - ### message.trailers - -* {Object} - -The `process.env` property returns an object containing the user environment. -See environ(7). - -An example of this object looks like: - -```js -{ - TERM: 'xterm-256color', - SHELL: '/usr/local/bin/bash', - USER: 'maciej', - PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin', - PWD: '/Users/maciej', - EDITOR: 'vim', - SHLVL: '1', - HOME: '/Users/maciej', - LOGNAME: 'maciej', - _: '/usr/local/bin/node' -} -``` - -It is possible to modify this object, but such modifications will not be -reflected outside the Node.js process. In other words, the following example -would not work: - -```console -$ node -e 'process.env.foo = "bar"' && echo $foo -``` - -While the following will: - -```js -process.env.foo = 'bar'; -console.log(process.env.foo); -``` - -Assigning a property on `process.env` will implicitly convert the value -to a string. - -Example: - -```js -process.env.test = null; -console.log(process.env.test); -// => 'null' -process.env.test = undefined; -console.log(process.env.test); -// => 'undefined' -``` - -Use `delete` to delete a property from `process.env`. - -Example: - -```js -process.env.TEST = 1; -delete process.env.TEST; -console.log(process.env.TEST); -// => undefined -``` - -On Windows operating systems, environment variables are case-insensitive. - -Example: - -```js -process.env.TEST = 1; -console.log(process.env.test); -// => 1 -``` - ## process.emitWarning(warning[, name][, ctor]) + +* {Object} + +The `process.env` property returns an object containing the user environment. +See environ(7). + +An example of this object looks like: + +```js +{ + TERM: 'xterm-256color', + SHELL: '/usr/local/bin/bash', + USER: 'maciej', + PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin', + PWD: '/Users/maciej', + EDITOR: 'vim', + SHLVL: '1', + HOME: '/Users/maciej', + LOGNAME: 'maciej', + _: '/usr/local/bin/node' +} +``` + +It is possible to modify this object, but such modifications will not be +reflected outside the Node.js process. In other words, the following example +would not work: + +```console +$ node -e 'process.env.foo = "bar"' && echo $foo +``` + +While the following will: + +```js +process.env.foo = 'bar'; +console.log(process.env.foo); +``` + +Assigning a property on `process.env` will implicitly convert the value +to a string. + +Example: + +```js +process.env.test = null; +console.log(process.env.test); +// => 'null' +process.env.test = undefined; +console.log(process.env.test); +// => 'undefined' +``` + +Use `delete` to delete a property from `process.env`. + +Example: + +```js +process.env.TEST = 1; +delete process.env.TEST; +console.log(process.env.TEST); +// => undefined +``` + +On Windows operating systems, environment variables are case-insensitive. + +Example: + +```js +process.env.TEST = 1; +console.log(process.env.test); +// => 1 +``` + ## process.execArgv - -The `'tlsClientError'` event is emitted when an error occurs before a secure -connection is established. The listener callback is passed two arguments when -called: - -* `exception` {Error} The `Error` object describing the error -* `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance from which the - error originated. - ### Event: 'newSession' + +The `'tlsClientError'` event is emitted when an error occurs before a secure +connection is established. The listener callback is passed two arguments when +called: + +* `exception` {Error} The `Error` object describing the error +* `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance from which the + error originated. + ### server.addContext(hostname, context) -Returns `true` if the peer certificate was signed by one of the CAs specified -when creating the `tls.TLSSocket` instance, otherwise `false`. +Returns the reason why the peer's certificate was not been verified. This +property is set only when `tlsSocket.authorized === false`. -### tlsSocket.authorizationError +### tlsSocket.authorized -Returns the reason why the peer's certificate was not been verified. This -property is set only when `tlsSocket.authorized === false`. +Returns `true` if the peer certificate was signed by one of the CAs specified +when creating the `tls.TLSSocket` instance, otherwise `false`. ### tlsSocket.encrypted - -* `port` {number} Default value for `options.port`. -* `host` {string} Optional default value for `options.host`. -* `options` {Object} See [`tls.connect()`][]. -* `callback` {Function} See [`tls.connect()`][]. - -Same as [`tls.connect()`][] except that `port` and `host` can be provided -as arguments instead of options. - -*Note*: A port or host option, if specified, will take precedence over any port -or host argument. - -## tls.connect(path[, options][, callback]) - - -* `path` {string} Default value for `options.path`. -* `options` {Object} See [`tls.connect()`][]. -* `callback` {Function} See [`tls.connect()`][]. - -Same as [`tls.connect()`][] except that `path` can be provided -as an argument instead of an option. - -*Note*: A path option, if specified, will take precedence over the path -argument. - ## tls.connect(options[, callback]) + +* `path` {string} Default value for `options.path`. +* `options` {Object} See [`tls.connect()`][]. +* `callback` {Function} See [`tls.connect()`][]. + +Same as [`tls.connect()`][] except that `path` can be provided +as an argument instead of an option. + +*Note*: A path option, if specified, will take precedence over the path +argument. + +## tls.connect(port[, host][, options][, callback]) + + +* `port` {number} Default value for `options.port`. +* `host` {string} Optional default value for `options.host`. +* `options` {Object} See [`tls.connect()`][]. +* `callback` {Function} See [`tls.connect()`][]. + +Same as [`tls.connect()`][] except that `port` and `host` can be provided +as arguments instead of options. + +*Note*: A port or host option, if specified, will take precedence over any port +or host argument. + ## tls.createSecureContext(options) + +A Symbol that can be used to declare custom inspect functions, see +[Custom inspection functions on Objects][]. + ### util.inspect.defaultOptions -A Symbol that can be used to declare custom inspect functions, see -[Custom inspection functions on Objects][]. +> Stability: 0 - Deprecated: Use [`Object.assign()`] instead. -## Deprecated APIs +The `util._extend()` method was never intended to be used outside of internal +Node.js modules. The community found and used it anyway. -The following APIs have been deprecated and should no longer be used. Existing -applications and modules should be updated to find alternative approaches. +It is deprecated and should not be used in new code. JavaScript comes with very +similar built-in functionality through [`Object.assign()`]. ### util.debug(string) - -> Stability: 0 - Deprecated: Use [`Object.assign()`] instead. - -The `util._extend()` method was never intended to be used outside of internal -Node.js modules. The community found and used it anyway. - -It is deprecated and should not be used in new code. JavaScript comes with very -similar built-in functionality through [`Object.assign()`]. - [`Array.isArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray [constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor [semantically incompatible]: https://github.com/nodejs/node/issues/4179 diff --git a/doc/api/v8.md b/doc/api/v8.md index 8cec6bdfdf8007..528f8967e2069e 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -9,45 +9,6 @@ const v8 = require('v8'); *Note*: The APIs and implementation are subject to change at any time. -## v8.getHeapStatistics() - - -Returns an object with the following properties: - -* `total_heap_size` {number} -* `total_heap_size_executable` {number} -* `total_physical_size` {number} -* `total_available_size` {number} -* `used_heap_size` {number} -* `heap_size_limit` {number} -* `malloced_memory` {number} -* `peak_malloced_memory` {number} -* `does_zap_garbage` {number} - -`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space` -option is enabled or not. This makes V8 overwrite heap garbage with a bit -pattern. The RSS footprint (resident memory set) gets bigger because it -continuously touches all heap pages and that makes them less likely to get -swapped out by the operating system. - -For example: - -```js -{ - total_heap_size: 7326976, - total_heap_size_executable: 4194304, - total_physical_size: 7326976, - total_available_size: 1152656, - used_heap_size: 3476208, - heap_size_limit: 1535115264, - malloced_memory: 16384, - peak_malloced_memory: 1127496, - does_zap_garbage: 0 -} -``` - ## v8.getHeapSpaceStatistics() + +Returns an object with the following properties: + +* `total_heap_size` {number} +* `total_heap_size_executable` {number} +* `total_physical_size` {number} +* `total_available_size` {number} +* `used_heap_size` {number} +* `heap_size_limit` {number} +* `malloced_memory` {number} +* `peak_malloced_memory` {number} +* `does_zap_garbage` {number} + +`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space` +option is enabled or not. This makes V8 overwrite heap garbage with a bit +pattern. The RSS footprint (resident memory set) gets bigger because it +continuously touches all heap pages and that makes them less likely to get +swapped out by the operating system. + +For example: + +```js +{ + total_heap_size: 7326976, + total_heap_size_executable: 4194304, + total_physical_size: 7326976, + total_available_size: 1152656, + used_heap_size: 3476208, + heap_size_limit: 1535115264, + malloced_memory: 16384, + peak_malloced_memory: 1127496, + does_zap_garbage: 0 +} +``` + ## v8.setFlagsFromString(string)