doc: document and test that methods return this

Also, add tests to ensure they will always return this, and to confirm
they return this when these doc changes are back-ported to earlier
release lines.

PR-URL: #13531
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

doc/api/net.md

@@ -52,6 +52,8 @@ This class is used to create a TCP or [IPC][] server.
 
 ## new net.Server([options][, connectionListener])
 
+* Returns: {net.Server}
+
 See [`net.createServer([options][, connectionListener])`][`net.createServer()`].
 
 `net.Server` is an [`EventEmitter`][] with the following events:
@@ -130,13 +132,17 @@ Don't call `server.address()` until the `'listening'` event has been emitted.
 added: v0.1.90
 -->
 
+* Returns: {net.Server}
+
 Stops the server from accepting new connections and keeps existing
 connections. This function is asynchronous, the server is finally
 closed when all connections are ended and the server emits a [`'close'`][] event.
 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
@@ -218,6 +224,7 @@ added: v0.5.10
 * `handle` {Object}
 * `backlog` {number} Common parameter of [`server.listen()`][] functions
 * `callback` {Function} Common parameter of [`server.listen()`][] functions
+* Returns: {net.Server}
 
 Start a server listening for connections on a given `handle` that has
 already been bound to a port, a UNIX domain socket, or a Windows named pipe.
@@ -243,6 +250,7 @@ added: v0.11.14
   * `exclusive` {boolean} Default to `false`
 * `callback` {Function} Common parameter of [`server.listen()`][]
   functions
+* Returns: {net.Server}
 
 If `port` is specified, it behaves the same as
 [`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host)`].
@@ -273,6 +281,7 @@ added: v0.1.90
   [Identifying paths for IPC connections][].
 * `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`.
 
@@ -284,6 +293,7 @@ added: v0.1.90
 * `host` {string}
 * `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`.
 
@@ -323,23 +333,23 @@ with [`child_process.fork()`][].
 added: v0.9.1
 -->
 
+* Returns: {net.Server}
+
 Opposite of `unref`, calling `ref` on a previously `unref`d server will *not*
 let the program exit if it's the only server left (the default behavior). If
 the server is `ref`d calling `ref` again will have no effect.
 
-Returns `server`.
-
 ### server.unref()
 <!-- YAML
 added: v0.9.1
 -->
 
+* Returns: {net.Server}
+
 Calling `unref` on a server will allow the program to exit if this is the only
 active server in the event system. If the server is already `unref`d calling
 `unref` again will have no effect.
 
-Returns `server`.
-
 ## Class: net.Socket
 <!-- YAML
 added: v0.3.4
@@ -532,6 +542,7 @@ Possible signatures:
   for [IPC][] connections.
 * [socket.connect(port[, host][, connectListener])][`socket.connect(port, host)`]
   for TCP connections.
+* Returns: {net.Socket} The socket itself.
 
 This function is asynchronous. When the connection is established, the
 [`'connect'`][] event will be emitted. If there is a problem connecting,
@@ -578,6 +589,8 @@ For [IPC][] connections, available `options` are:
 * `path` {string} Required. Path the client should connect to.
   See [Identifying paths for IPC connections][].
 
+Returns `socket`.
+
 #### socket.connect(path[, connectListener])
 
 * `path` {string} Path the client should connect to. See
@@ -592,6 +605,8 @@ 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
@@ -609,6 +624,8 @@ 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
@@ -642,14 +659,14 @@ connection is destroyed no further data can be transferred using it.
 added: v0.1.90
 -->
 
+* Returns: {net.Socket} The socket itself.
+
 Half-closes the socket. i.e., it sends a FIN packet. It is possible the
 server will still send some data.
 
 If `data` is specified, it is equivalent to calling
 `socket.write(data, encoding)` followed by [`socket.end()`][].
 
-Returns `socket`.
-
 ### socket.localAddress
 <!-- YAML
 added: v0.9.6
@@ -670,6 +687,8 @@ The numeric representation of the local port. For example,
 
 ### socket.pause()
 
+* Returns: {net.Socket} The socket itself.
+
 Pauses the reading of data. That is, [`'data'`][] events will not be emitted.
 Useful to throttle back an upload.
 
@@ -678,12 +697,12 @@ Useful to throttle back an upload.
 added: v0.9.1
 -->
 
+* Returns: {net.Socket} The socket itself.
+
 Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not*
 let the program exit if it's the only socket left (the default behavior). If
 the socket is `ref`d calling `ref` again will have no effect.
 
-Returns `socket`.
-
 ### socket.remoteAddress
 <!-- YAML
 added: v0.5.10
@@ -710,13 +729,17 @@ The numeric representation of the remote port. For example,
 
 ### socket.resume()
 
+* Returns: {net.Socket} The socket itself.
+
 Resumes reading after a call to [`socket.pause()`][].
 
 ### socket.setEncoding([encoding])
 <!-- YAML
 added: v0.1.90
 -->
 
+* Returns: {net.Socket} The socket itself.
+
 Set the encoding for the socket as a [Readable Stream][]. See
 [`stream.setEncoding()`][] for more information.
 
@@ -725,6 +748,8 @@ Set the encoding for the socket as a [Readable Stream][]. See
 added: v0.1.92
 -->
 
+* Returns: {net.Socket} The socket itself.
+
 Enable/disable keep-alive functionality, and optionally set the initial
 delay before the first keepalive probe is sent on an idle socket.
 `enable` defaults to `false`.
@@ -734,25 +759,25 @@ data packet received and the first keepalive probe. Setting 0 for
 initialDelay will leave the value unchanged from the default
 (or previous) setting. Defaults to `0`.
 
-Returns `socket`.
-
 ### socket.setNoDelay([noDelay])
 <!-- YAML
 added: v0.1.90
 -->
 
+* Returns: {net.Socket} The socket itself.
+
 Disables the Nagle algorithm. By default TCP connections use the Nagle
 algorithm, they buffer data before sending it off. Setting `true` for
 `noDelay` will immediately fire off data each time `socket.write()` is called.
 `noDelay` defaults to `true`.
 
-Returns `socket`.
-
 ### socket.setTimeout(timeout[, callback])
 <!-- YAML
 added: v0.1.90
 -->
 
+* Returns: {net.Socket} The socket itself.
+
 Sets the socket to timeout after `timeout` milliseconds of inactivity on
 the socket. By default `net.Socket` do not have a timeout.
 
@@ -773,19 +798,17 @@ If `timeout` is 0, then the existing idle timeout is disabled.
 The optional `callback` parameter will be added as a one time listener for the
 [`'timeout'`][] event.
 
-Returns `socket`.
-
 ### socket.unref()
 <!-- YAML
 added: v0.9.1
 -->
 
+* Returns: {net.Socket} The socket itself.
+
 Calling `unref` on a socket will allow the program to exit if this is the only
 active socket in the event system. If the socket is already `unref`d calling
 `unref` again will have no effect.
 
-Returns `socket`.
-
 ### socket.write(data[, encoding][, callback])
 <!-- YAML
 added: v0.1.90
@@ -965,6 +988,7 @@ Creates a new TCP or [IPC][] server.
     should be paused on incoming connections.
 * `connectionListener` {Function} Automatically set as a listener for the
   [`'connection'`][] event
+* Returns: {net.Server}
 
 If `allowHalfOpen` is set to `true`, when the other end of the socket
 sends a FIN packet, the server will only send a FIN packet back when

test/parallel/test-net-end-close.js

@@ -14,7 +14,7 @@ const s = new net.Socket({
   },
   writable: false
 });
-s.resume();
+assert.strictEqual(s, s.resume());
 
 const events = [];
 

test/parallel/test-net-server-close.js

@@ -44,7 +44,7 @@ const server = net.createServer(function(c) {
   sockets.push(c);
 
   if (sockets.length === 2) {
-    server.close();
+    assert.strictEqual(server.close(), server);
     sockets.forEach(function(c) { c.destroy(); });
   }
 });
@@ -53,7 +53,7 @@ server.on('close', function() {
   events.push('server');
 });
 
-server.listen(0, function() {
+assert.strictEqual(server, server.listen(0, function() {
   net.createConnection(this.address().port);
   net.createConnection(this.address().port);
-});
+}));

test/parallel/test-net-socket-local-address.js

@@ -34,7 +34,10 @@ function connect() {
 
   conns++;
   client.once('close', connect);
-  client.connect(server.address().port, common.localhostIPv4, () => {
-    clientLocalPorts.push(client.localPort);
-  });
+  assert.strictEqual(
+    client,
+    client.connect(server.address().port, common.localhostIPv4, () => {
+      clientLocalPorts.push(client.localPort);
+    })
+  );
 }

test/parallel/test-net-stream.js

@@ -61,7 +61,7 @@ const server = net.createServer(function(socket) {
 }).listen(0, function() {
   const conn = net.connect(this.address().port);
   conn.on('data', function(buf) {
-    conn.pause();
+    assert.strictEqual(conn, conn.pause());
     setTimeout(function() {
       conn.destroy();
     }, 20);