doc: add and unify even more return values

PR-URL: #19955 Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>
nodejs · Apr 16, 2018 · 31b5ed4 · 31b5ed4
1 parent 0be14de
commit 31b5ed4
Show file tree

Hide file tree

Showing 20 changed files with 180 additions and 24 deletions.
diff --git 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

diff --git 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.

diff --git 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.

diff --git 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`).

diff --git 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][].

diff --git 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

diff --git 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

diff --git 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

diff --git 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

diff --git 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

diff --git 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.
 

diff --git 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