doc: add and unify even more return values

PR-URL: https://github.com/nodejs/node/pull/19955 Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>
2018-04-11 21:07:14 +03:00 · 2018-04-11 21:07:14 +03:00 · df5d41bf93
commit df5d41bf93
parent 068c001dee
20 changed files with 180 additions and 24 deletions
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@ -1407,6 +1407,7 @@ deprecated: v0.11.13
 > Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead.

 - `details` {Object} Identical to [`tls.createSecureContext()`][].
+- Returns: {tls.SecureContext}

 The `crypto.createCredentials()` method is a deprecated function for creating
 and returning a `tls.SecureContext`. It should not be used. Replace it with
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@ -100,6 +100,8 @@ available interface, call `addMembership` multiple times, once per interface.
 added: v0.1.99
 -->

+* Returns: {Object}
+
 Returns an object containing the address information for a socket.
 For UDP sockets, this object will contain `address`, `family` and `port`
 properties.
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@ -110,6 +110,8 @@ callbacks will be called with an error with code `ECANCELLED`.
 added: v0.11.3
 -->

+* Returns: {string[]}
+
 Returns an array of IP address strings, formatted according to [rfc5952][],
 that are currently configured for DNS resolution. A string will include a port
 section if a custom port is used.
--- a/doc/api/events.md
+++ b/doc/api/events.md
@ -298,6 +298,7 @@ added: v0.1.26
 -->
 - `eventName` {string|symbol}
 - `...args` {any}
+- Returns: {boolean}

 Synchronously calls each of the listeners registered for the event named
 `eventName`, in the order they were registered, passing the supplied arguments
@ -310,6 +311,8 @@ Returns `true` if the event had listeners, `false` otherwise.
 added: v6.0.0
 -->

+- Returns: {Array}
+
 Returns an array listing the events for which the emitter has registered
 listeners. The values in the array will be strings or Symbols.

@ -331,6 +334,8 @@ console.log(myEE.eventNames());
 added: v1.0.0
 -->

+- Returns: {integer}
+
 Returns the current max listener value for the `EventEmitter` which is either
 set by [`emitter.setMaxListeners(n)`][] or defaults to
 [`EventEmitter.defaultMaxListeners`][].
@ -341,6 +346,7 @@ added: v3.2.0
 -->

 * `eventName` {string|symbol} The name of the event being listened for
+* Returns: {integer}

 Returns the number of listeners listening to the event named `eventName`.

@ -354,6 +360,7 @@ changes:
                 original listeners instead of wrapper functions now.
 -->
 - `eventName` {string|symbol}
+- Returns: {Function[]}

 Returns a copy of the array of listeners for the event named `eventName`.

@ -372,6 +379,7 @@ added: v0.1.101

 * `eventName` {string|symbol} The name of the event.
 * `listener` {Function} The callback function
+* Returns: {EventEmitter}

 Adds the `listener` function to the end of the listeners array for the
 event named `eventName`. No checks are made to see if the `listener` has
@ -408,6 +416,7 @@ added: v0.3.0

 * `eventName` {string|symbol} The name of the event.
 * `listener` {Function} The callback function
+* Returns: {EventEmitter}

 Adds a **one-time** `listener` function for the event named `eventName`. The
 next time `eventName` is triggered, this listener is removed and then invoked.
@ -441,6 +450,7 @@ added: v6.0.0

 * `eventName` {string|symbol} The name of the event.
 * `listener` {Function} The callback function
+* Returns: {EventEmitter}

 Adds the `listener` function to the *beginning* of the listeners array for the
 event named `eventName`. No checks are made to see if the `listener` has
@ -463,6 +473,7 @@ added: v6.0.0

 * `eventName` {string|symbol} The name of the event.
 * `listener` {Function} The callback function
+* Returns: {EventEmitter}

 Adds a **one-time** `listener` function for the event named `eventName` to the
 *beginning* of the listeners array. The next time `eventName` is triggered, this
@ -481,6 +492,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
 added: v0.1.26
 -->
 - `eventName` {string|symbol}
+- Returns: {EventEmitter}

 Removes all listeners, or those of the specified `eventName`.

@ -496,6 +508,7 @@ added: v0.1.26
 -->
 - `eventName` {string|symbol}
 - `listener` {Function}
+- Returns: {EventEmitter}

 Removes the specified `listener` from the listener array for the event named
 `eventName`.
@ -564,6 +577,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
 added: v0.3.5
 -->
 - `n` {integer}
+- Returns: {EventEmitter}

 By default EventEmitters will print a warning if more than `10` listeners are
 added for a particular event. This is a useful default that helps finding
@ -579,6 +593,7 @@ Returns a reference to the `EventEmitter`, so that calls can be chained.
 added: v9.4.0
 -->
 - `eventName` {string|symbol}
+- Returns: {Function[]}

 Returns a copy of the array of listeners for the event named `eventName`,
 including any wrappers (such as those created by `.once`).
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@ -1154,6 +1154,8 @@ Synchronous close(2). Returns `undefined`.

 ## fs.constants

+* {Object}
+
 Returns an object containing commonly used constants for file system
 operations. The specific constants currently defined are described in
 [FS Constants][].
--- a/doc/api/http.md
+++ b/doc/api/http.md
@ -662,12 +662,11 @@ added: v0.5.9
 * `timeout` {number} Milliseconds before a request times out.
 * `callback` {Function} Optional function to be called when a timeout occurs.
  Same as binding to the `timeout` event.
+* Returns: {http.ClientRequest}

 Once a socket is assigned to this request and is connected
 [`socket.setTimeout()`][] will be called.

-Returns `request`.
-
 ### request.socket
 <!-- YAML
 added: v0.3.0
@ -706,6 +705,7 @@ added: v0.1.29
 * `chunk` {string|Buffer}
 * `encoding` {string}
 * `callback` {Function}
+* Returns: {boolean}

 Sends a chunk of the body. By calling this method
 many times, a request body can be sent to a
@ -928,6 +928,7 @@ added: v0.9.12

 * `msecs` {number} **Default:** `120000` (2 minutes)
 * `callback` {Function}
+* Returns: {http.Server}

 Sets the timeout value for sockets, and emits a `'timeout'` event on
 the Server object, passing the socket as an argument, if a timeout
@ -940,8 +941,6 @@ By default, the Server's timeout value is 2 minutes, and sockets are
 destroyed automatically if they time out. However, if a callback is assigned
 to the Server's `'timeout'` event, timeouts must be handled explicitly.

-Returns `server`.
-
 ### server.timeout
 <!-- YAML
 added: v0.9.12
@ -1248,6 +1247,7 @@ added: v0.9.12

 * `msecs` {number}
 * `callback` {Function}
+* Returns: {http.ServerResponse}

 Sets the Socket's timeout value to `msecs`. If a callback is
 provided, then it is added as a listener on the `'timeout'` event on
@ -1258,8 +1258,6 @@ the server, then sockets are destroyed when they time out. If a handler is
 assigned to the request, the response, or the server's `'timeout'` events,
 timed out sockets must be handled explicitly.

-Returns `response`.
-
 ### response.socket
 <!-- YAML
 added: v0.3.0
@ -1579,11 +1577,10 @@ added: v0.5.9

 * `msecs` {number}
 * `callback` {Function}
+* Returns: {http.IncomingMessage}

 Calls `message.connection.setTimeout(msecs, callback)`.

-Returns `message`.
-
 ### message.socket
 <!-- YAML
 added: v0.3.0
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@ -2489,6 +2489,7 @@ added: v8.4.0

 * `msecs` {number}
 * `callback` {Function}
+* Returns: {http2.Http2ServerRequest}

 Sets the [`Http2Stream`]()'s timeout value to `msecs`. If a callback is
 provided, then it is added as a listener on the `'timeout'` event on
@ -2499,8 +2500,6 @@ the server, then [`Http2Stream`]()s are destroyed when they time out. If a
 handler is assigned to the request, the response, or the server's `'timeout'`
 events, timed out sockets must be handled explicitly.

-Returns `request`.
-
 #### request.socket
 <!-- YAML
 added: v8.4.0
@ -2866,6 +2865,7 @@ added: v8.4.0

 * `msecs` {number}
 * `callback` {Function}
+* Returns: {http2.Http2ServerResponse}

 Sets the [`Http2Stream`]()'s timeout value to `msecs`. If a callback is
 provided, then it is added as a listener on the `'timeout'` event on
@ -2876,8 +2876,6 @@ the server, then [`Http2Stream`]()s are destroyed when they time out. If a
 handler is assigned to the request, the response, or the server's `'timeout'`
 events, timed out sockets must be handled explicitly.

-Returns `response`.
-
 #### response.socket
 <!-- YAML
 added: v8.4.0
--- a/doc/api/inspector.md
+++ b/doc/api/inspector.md
@ -34,6 +34,8 @@ Deactivate the inspector. Blocks until there are no active connections.

 ### inspector.url()

+* Returns: {string|undefined}
+
 Return the URL of the active inspector, or `undefined` if there is none.

 ## Class: inspector.Session
--- a/doc/api/net.md
+++ b/doc/api/net.md
@ -112,6 +112,8 @@ Emitted when the server has been bound after calling [`server.listen()`][].
 added: v0.1.90
 -->

+* Returns: {Object}
+
 Returns the bound address, the address family name, and port of the server
 as reported by the operating system if listening on an IP socket.
 Useful to find which port was assigned when getting an OS-assigned address.
@ -153,8 +155,6 @@ The optional `callback` will be called once the `'close'` event occurs. Unlike
 that event, it will be called with an Error as its only argument if the server
 was not open when it was closed.

-Returns `server`.
-
 ### server.connections
 <!-- YAML
 added: v0.2.0
@ -500,6 +500,8 @@ See also: [`socket.setTimeout()`][]
 added: v0.1.90
 -->

+* Returns: {Object}
+
 Returns the bound address, the address family name and port of the
 socket as reported by the operating system. Returns an object with
 three properties, e.g.
@ -601,8 +603,6 @@ For [IPC][] connections, available `options` are:
  See [Identifying paths for IPC connections][]. If provided, the TCP-specific
  options above are ignored.

-Returns `socket`.
-
 #### socket.connect(path[, connectListener])

 * `path` {string} Path the client should connect to. See
@ -617,8 +617,6 @@ Alias to
 [`socket.connect(options[, connectListener])`][`socket.connect(options)`]
 called with `{ path: path }` as `options`.

-Returns `socket`.
-
 #### socket.connect(port[, host][, connectListener])
 <!-- YAML
 added: v0.1.90
@ -636,8 +634,6 @@ Alias to
 [`socket.connect(options[, connectListener])`][`socket.connect(options)`]
 called with `{port: port, host: host}` as `options`.

-Returns `socket`.
-
 ### socket.connecting
 <!-- YAML
 added: v6.1.0
@ -829,6 +825,8 @@ active socket in the event system. If the socket is already `unref`d calling
 added: v0.1.90
 -->

+* Returns: {boolean}
+
 Sends data on the socket. The second parameter specifies the encoding in the
 case of a string — it defaults to UTF8 encoding.

@ -1068,24 +1066,29 @@ $ nc -U /tmp/echo.sock
 added: v0.3.0
 -->

-Tests if input is an IP address. Returns 0 for invalid strings,
-returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.
+* Returns: {integer}

+Tests if input is an IP address. Returns `0` for invalid strings,
+returns `4` for IP version 4 addresses, and returns `6` for IP version 6
+addresses.

 ## net.isIPv4(input)
 <!-- YAML
 added: v0.3.0
 -->

-Returns true if input is a version 4 IP address, otherwise returns false.
+* Returns: {boolean}

+Returns `true` if input is a version 4 IP address, otherwise returns `false`.

 ## net.isIPv6(input)
 <!-- YAML
 added: v0.3.0
 -->

-Returns true if input is a version 6 IP address, otherwise returns false.
+* Returns: {boolean}
+
+Returns `true` if input is a version 6 IP address, otherwise returns `false`.

 [`'close'`]: #net_event_close
 [`'connect'`]: #net_event_connect
--- a/doc/api/punycode.md
+++ b/doc/api/punycode.md
@ -145,6 +145,8 @@ punycode.ucs2.encode([0x1D306]); // '\uD834\uDF06'
 added: v0.6.1
 -->

+* {string}
+
 Returns a string identifying the current [Punycode.js][] version number.

 [Punycode.js]: https://mths.be/punycode
--- a/doc/api/repl.md
+++ b/doc/api/repl.md
@ -411,6 +411,7 @@ deprecated: v9.0.0

 * `keyword` {string} the potential keyword to parse and execute
 * `rest` {any} any parameters to the keyword command
+* Returns: {boolean}

 > Stability: 0 - Deprecated.

--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@ -462,6 +462,9 @@ See also: [`writable.cork()`][].
 <!-- YAML
 added: v9.3.0
 -->
+
+* {number}
+
 Return the value of `highWaterMark` passed when constructing this
 `Writable`.

@ -1209,6 +1212,8 @@ added: REPLACEME

 > Stability: 1 - Experimental

+* {AsyncIterator}
+
 Returns an [AsyncIterator][async-iterator] to fully consume the stream.

 ```js
--- a/doc/api/string_decoder.md
+++ b/doc/api/string_decoder.md
@ -58,6 +58,7 @@ added: v0.9.3
 -->

 * `buffer` {Buffer} A `Buffer` containing the bytes to decode.
+* Returns: {string}

 Returns any remaining input stored in the internal buffer as a string. Bytes
 representing incomplete UTF-8 and UTF-16 characters will be replaced with
@ -77,6 +78,7 @@ changes:
 -->

 * `buffer` {Buffer} A `Buffer` containing the bytes to decode.
+* Returns: {string}

 Returns a decoded string, ensuring that any incomplete multibyte characters at
 the end of the `Buffer` are omitted from the returned string and stored in an
--- a/doc/api/timers.md
+++ b/doc/api/timers.md
@ -28,6 +28,8 @@ functions that can be used to control this default behavior.
 added: v9.7.0
 -->

+* Returns: {Immediate}
+
 When called, requests that the Node.js event loop *not* exit so long as the
 `Immediate` is active. Calling `immediate.ref()` multiple times will have no
 effect.
@ -42,6 +44,8 @@ Returns a reference to the `Immediate`.
 added: v9.7.0
 -->

+* Returns: {Immediate}
+
 When called, the active `Immediate` object will not require the Node.js event
 loop to remain active. If there is no other activity keeping the event loop
 running, the process may exit before the `Immediate` object's callback is
@ -66,6 +70,8 @@ control this default behavior.
 added: v0.9.1
 -->

+* Returns: {Timeout}
+
 When called, requests that the Node.js event loop *not* exit so long as the
 `Timeout` is active. Calling `timeout.ref()` multiple times will have no effect.

@ -79,6 +85,8 @@ Returns a reference to the `Timeout`.
 added: v0.9.1
 -->

+* Returns: {Timeout}
+
 When called, the active `Timeout` object will not require the Node.js event loop
 to remain active. If there is no other activity keeping the event loop running,
 the process may exit before the `Timeout` object's callback is invoked. Calling
@ -147,6 +155,7 @@ added: v0.0.1
 * `delay` {number} The number of milliseconds to wait before calling the
  `callback`.
 * `...args` {any} Optional arguments to pass when the `callback` is called.
+* Returns: {Timeout}

 Schedules repeated execution of `callback` every `delay` milliseconds.
 Returns a `Timeout` for use with [`clearInterval()`][].
@ -165,6 +174,7 @@ added: v0.0.1
 * `delay` {number} The number of milliseconds to wait before calling the
  `callback`.
 * `...args` {any} Optional arguments to pass when the `callback` is called.
+* Returns: {Timeout}

 Schedules execution of a one-time `callback` after `delay` milliseconds.
 Returns a `Timeout` for use with [`clearTimeout()`][].
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@ -365,6 +365,8 @@ the client request's SNI hostname matches the supplied `hostname` (or wildcard).
 added: v0.6.0
 -->

+* Returns: {Object}
+
 Returns the bound address, the address family name, and port of the
 server as reported by the operating system. See [`net.Server.address()`][] for
 more information.
@ -390,6 +392,8 @@ deprecated: v0.9.7

 > Stability: 0 - Deprecated: Use [`server.getConnections()`][] instead.

+* {number}
+
 Returns the current number of concurrent connections on the server.

 ### server.getTicketKeys()
@ -397,6 +401,8 @@ Returns the current number of concurrent connections on the server.
 added: v3.0.0
 -->

+* Returns: {Buffer}
+
 Returns a `Buffer` instance holding the keys currently used for
 encryption/decryption of the [TLS Session Tickets][]

@ -509,6 +515,8 @@ protocol.
 added: v0.11.4
 -->

+* Returns: {Object}
+
 Returns the bound address, the address family name, and port of the
 underlying socket as reported by the operating system. Returns an
 object with three properties, e.g.
@ -527,6 +535,8 @@ property is set only when `tlsSocket.authorized === false`.
 added: v0.11.4
 -->

+* Returns: {boolean}
+
 Returns `true` if the peer certificate was signed by one of the CAs specified
 when creating the `tls.TLSSocket` instance, otherwise `false`.

@ -551,6 +561,8 @@ Always returns `true`. This may be used to distinguish TLS sockets from regular
 added: v0.11.4
 -->

+* Returns: {Object}
+
 Returns an object representing the cipher name. The `version` key is a legacy
 field which always contains the value `'TLSv1/SSLv3'`.

@ -565,6 +577,8 @@ information.
 added: v5.0.0
 -->

+* Returns: {Object}
+
 Returns an object representing the type, name, and size of parameter of
 an ephemeral key exchange in [Perfect Forward Secrecy][] on a client
 connection. It returns an empty object when the key exchange is not
@ -598,6 +612,7 @@ added: v0.11.4

 * `detailed` {boolean} Include the full certificate chain if `true`, otherwise
  include just the peer's certificate.
+* Returns: {Object}

 Returns an object representing the peer's certificate. The returned object has
 some properties corresponding to the fields of the certificate.
@ -658,6 +673,8 @@ to implement the `tls-unique` channel binding from [RFC 5929][].
 added: v5.7.0
 -->

+* Returns: {string}
+
 Returns a string containing the negotiated SSL/TLS protocol version of the
 current connection. The value `'unknown'` will be returned for connected
 sockets that have not completed the handshaking process. The value `null` will
@ -698,6 +715,8 @@ reuse provide `session` option to [`tls.connect()`][].
 added: v0.11.4
 -->

+* {string}
+
 Returns the string representation of the local IP address.

 ### tlsSocket.localPort
@ -705,6 +724,8 @@ Returns the string representation of the local IP address.
 added: v0.11.4
 -->

+* {number}
+
 Returns the numeric representation of the local port.

 ### tlsSocket.remoteAddress
@ -712,6 +733,8 @@ Returns the numeric representation of the local port.
 added: v0.11.4
 -->

+* {string}
+
 Returns the string representation of the remote IP address. For example,
 `'74.125.127.100'` or `'2001:4860:a005::68'`.

@ -720,6 +743,8 @@ Returns the string representation of the remote IP address. For example,
 added: v0.11.4
 -->

+* {string}
+
 Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`.

 ### tlsSocket.remotePort
@ -727,6 +752,8 @@ Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`.
 added: v0.11.4
 -->

+* {number}
+
 Returns the numeric representation of the remote port. For example, `443`.

 ### tlsSocket.renegotiate(options, callback)
@ -760,6 +787,7 @@ added: v0.11.11

 * `size` {number} The maximum TLS fragment size. The maximum value is `16384`.
  **Default:** `16384`.
+* Returns: {boolean}

 The `tlsSocket.setMaxSendFragment()` method sets the maximum TLS fragment size.
 Returns `true` if setting the limit succeeded; `false` otherwise.
@ -779,6 +807,7 @@ added: v0.8.4
 * `host` {string} The hostname to verify the certificate against
 * `cert` {Object} An object representing the peer's certificate. The returned
  object has some properties corresponding to the fields of the certificate.
+* Returns: {Error|undefined}

 Verifies the certificate `cert` is issued to host `host`.

@ -1216,6 +1245,8 @@ openssl s_client -connect 127.0.0.1:8000
 added: v0.10.2
 -->

+* Returns: {string[]}
+
 Returns an array with the names of the supported SSL ciphers.

 For example:
--- a/doc/api/url.md
+++ b/doc/api/url.md
@ -818,6 +818,7 @@ added: v7.6.0
  * `unicode` {boolean} `true` if Unicode characters appearing in the host
    component of the URL string should be encoded directly as opposed to being
    Punycode encoded. **Default:** `false`.
+* Returns: {string}

 Returns a customizable serialization of a URL String representation of a
 [WHATWG URL][] object.
--- a/doc/api/util.md
+++ b/doc/api/util.md
@ -938,6 +938,8 @@ useful for addon developers who prefer to do type checking in JavaScript.
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`ArrayBuffer`][] or
 [`SharedArrayBuffer`][] instance.

@ -956,6 +958,8 @@ util.types.isAnyArrayBuffer(new SharedArrayBuffer());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is an `arguments` object.

 For example:
@ -972,6 +976,8 @@ function foo() {
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`ArrayBuffer`][] instance.
 This does *not* include [`SharedArrayBuffer`][] instances. Usually, it is
 desirable to test for both; See [`util.types.isAnyArrayBuffer()`][] for that.
@ -988,6 +994,8 @@ util.types.isArrayBuffer(new SharedArrayBuffer());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is an [async function][].
 Note that this only reports back what the JavaScript engine is seeing;
 in particular, the return value may not match the original source code if
@ -1005,6 +1013,8 @@ util.types.isAsyncFunction(async function foo() {});  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a boolean object, e.g. created
 by `new Boolean()`.

@ -1024,6 +1034,8 @@ util.types.isBooleanObject(Boolean(true)); // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`DataView`][] instance.

 For example:
@ -1041,6 +1053,8 @@ See also [`ArrayBuffer.isView()`][].
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Date`][] instance.

 For example:
@ -1054,6 +1068,8 @@ util.types.isDate(new Date());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a native `External` value.

 ### util.types.isFloat32Array(value)
@ -1061,6 +1077,8 @@ Returns `true` if the value is a native `External` value.
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Float32Array`][] instance.

 For example:
@ -1076,6 +1094,8 @@ util.types.isFloat32Array(new Float64Array());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Float64Array`][] instance.

 For example:
@ -1091,6 +1111,8 @@ util.types.isFloat64Array(new Float64Array());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a generator function.
 Note that this only reports back what the JavaScript engine is seeing;
 in particular, the return value may not match the original source code if
@ -1108,6 +1130,8 @@ util.types.isGeneratorFunction(function* foo() {});  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a generator object as returned from a
 built-in generator function.
 Note that this only reports back what the JavaScript engine is seeing;
@ -1127,6 +1151,8 @@ util.types.isGeneratorObject(generator);  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Int8Array`][] instance.

 For example:
@ -1142,6 +1168,8 @@ util.types.isInt8Array(new Float64Array());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Int16Array`][] instance.

 For example:
@ -1157,6 +1185,8 @@ util.types.isInt16Array(new Float64Array());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Int32Array`][] instance.

 For example:
@ -1172,6 +1202,8 @@ util.types.isInt32Array(new Float64Array());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Map`][] instance.

 For example:
@ -1185,6 +1217,8 @@ util.types.isMap(new Map());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is an iterator returned for a built-in
 [`Map`][] instance.

@ -1203,6 +1237,8 @@ util.types.isMapIterator(map[Symbol.iterator]());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is an instance of a built-in [`Error`][] type.

 For example:
@ -1218,6 +1254,8 @@ util.types.isNativeError(new RangeError());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a number object, e.g. created
 by `new Number()`.

@ -1233,6 +1271,8 @@ util.types.isNumberObject(new Number(0));   // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Promise`][].

 For example:
@ -1246,6 +1286,8 @@ util.types.isPromise(Promise.resolve(42));  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a [`Proxy`][] instance.

 For example:
@ -1262,6 +1304,8 @@ util.types.isProxy(proxy);  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a regular expression object.

 For example:
@ -1276,6 +1320,8 @@ util.types.isRegExp(new RegExp('abc'));  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Set`][] instance.

 For example:
@ -1289,6 +1335,8 @@ util.types.isSet(new Set());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is an iterator returned for a built-in
 [`Set`][] instance.

@ -1307,6 +1355,8 @@ util.types.isSetIterator(set[Symbol.iterator]());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`SharedArrayBuffer`][] instance.
 This does *not* include [`ArrayBuffer`][] instances. Usually, it is
 desirable to test for both; See [`util.types.isAnyArrayBuffer()`][] for that.
@ -1323,6 +1373,8 @@ util.types.isSharedArrayBuffer(new SharedArrayBuffer());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a string object, e.g. created
 by `new String()`.

@ -1338,6 +1390,8 @@ util.types.isStringObject(new String('foo'));   // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a symbol object, created
 by calling `Object()` on a `Symbol` primitive.

@ -1354,6 +1408,8 @@ util.types.isSymbolObject(Object(symbol));   // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`TypedArray`][] instance.

 For example:
@ -1371,6 +1427,8 @@ See also [`ArrayBuffer.isView()`][].
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Uint8Array`][] instance.

 For example:
@ -1386,6 +1444,8 @@ util.types.isUint8Array(new Float64Array());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Uint8ClampedArray`][] instance.

 For example:
@ -1401,6 +1461,8 @@ util.types.isUint8ClampedArray(new Float64Array());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Uint16Array`][] instance.

 For example:
@ -1416,6 +1478,8 @@ util.types.isUint16Array(new Float64Array());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`Uint32Array`][] instance.

 For example:
@ -1431,6 +1495,8 @@ util.types.isUint32Array(new Float64Array());  // Returns false
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`WeakMap`][] instance.

 For example:
@ -1444,6 +1510,8 @@ util.types.isWeakMap(new WeakMap());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`WeakSet`][] instance.

 For example:
@ -1457,6 +1525,8 @@ util.types.isWeakSet(new WeakSet());  // Returns true
 added: REPLACEME
 -->

+* Returns: {boolean}
+
 Returns `true` if the value is a built-in [`WebAssembly.Module`][] instance.

 For example:
--- a/doc/api/v8.md
+++ b/doc/api/v8.md
@ -16,6 +16,8 @@ The APIs and implementation are subject to change at any time.
 added: v8.0.0
 -->

+* Returns: {integer}
+
 Returns an integer representing a "version tag" derived from the V8 version,
 command line flags and detected CPU features. This is useful for determining
 whether a [`vm.Script`][] `cachedData` buffer is compatible with this instance
@ -30,6 +32,8 @@ changes:
    description: Support values exceeding the 32-bit unsigned integer range.
 -->

+* Returns: {Object[]}
+
 Returns statistics about the V8 heap spaces, i.e. the segments which make up
 the V8 heap. Neither the ordering of heap spaces, nor the availability of a
 heap space can be guaranteed as the statistics are provided via the V8
@ -96,6 +100,8 @@ changes:
    description: Support values exceeding the 32-bit unsigned integer range.
 -->

+* Returns: {Object}
+
 Returns an object with the following properties:

 * `total_heap_size` {number}
@ -204,6 +210,8 @@ This throws an error if `value` cannot be serialized.

 #### serializer.releaseBuffer()

+* Returns: {Buffer}
+
 Returns the stored internal buffer. This serializer should not be used once
 the buffer is released. Calling this method results in undefined behavior
 if a previous write has failed.
--- a/doc/api/vm.md
+++ b/doc/api/vm.md
@ -684,6 +684,7 @@ added: v0.11.7
 -->

 * `sandbox` {Object}
+* Returns: {boolean}

 Returns `true` if the given `sandbox` object has been [contextified][] using
 [`vm.createContext()`][].
--- a/tools/doc/type-parser.js
+++ b/tools/doc/type-parser.js
@ -29,6 +29,8 @@ const customTypesMap = {

  'this': `${jsDocPrefix}Reference/Operators/this`,

+  'AsyncIterator': 'https://github.com/tc39/proposal-async-iteration',
+
  'Iterable':
    `${jsDocPrefix}Reference/Iteration_protocols#The_iterable_protocol`,
  'Iterator':
@ -105,6 +107,7 @@ const customTypesMap = {
  'Timeout': 'timers.html#timers_class_timeout',
  'Timer': 'timers.html#timers_timers',

+  'tls.SecureContext': 'tls.html#tls_tls_createsecurecontext_options',
  'tls.Server': 'tls.html#tls_class_tls_server',
  'tls.TLSSocket': 'tls.html#tls_class_tls_tlssocket',