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: https://github.com/nodejs/node/pull/13553
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

doc/api/net.md

@@ -89,6 +89,8 @@ 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.
@@ -96,6 +98,8 @@ 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
@@ -128,6 +132,7 @@ added: v0.5.10
 * `handle` {Object}
 * `backlog` {number}
 * `callback` {Function}
+* Returns: {net.Server}
 
 The `handle` object can be set to either a server or socket (anything
 with an underlying `_handle` member), or a `{fd: <n>}` object.
@@ -158,6 +163,7 @@ added: v0.11.14
   * `path` {string} - Optional.
   * `exclusive` {boolean} - Optional.
 * `callback` {Function} - Optional.
+* Returns: {net.Server}
 
 The `port`, `host`, and `backlog` properties of `options`, as well as the
 optional callback function, behave as they do on a call to
@@ -189,6 +195,7 @@ added: v0.1.90
 * `path` {string}
 * `backlog` {number}
 * `callback` {Function}
+* Returns: {net.Server}
 
 Start a local socket server listening for connections on the given `path`.
 
@@ -227,6 +234,7 @@ subsequent call will *re-open* the server using the provided options.
 <!-- YAML
 added: v0.1.90
 -->
+* Returns: {net.Server}
 
 Begin accepting connections on the specified `port` and `hostname`. If the
 `hostname` is omitted, the server will accept connections on any IPv6 address
@@ -289,23 +297,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
@@ -501,6 +509,10 @@ specifies:
 
   - `path`: Path the client should connect to (Required).
 
+For either case:
+
+* Returns: {net.Socket} The socket itself.
+
 Normally this method is not needed, as `net.createConnection` opens the
 socket. Use this only if you are implementing a custom Socket.
 
@@ -520,6 +532,8 @@ added: v0.1.90
 As [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`],
 with options as either `{port: port, host: host}` or `{path: path}`.
 
+* Returns: {net.Socket} The socket itself.
+
 ### socket.connecting
 <!-- YAML
 added: v6.1.0
@@ -550,6 +564,8 @@ 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.
 
@@ -575,6 +591,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.
 
@@ -583,12 +601,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
@@ -615,6 +633,8 @@ The numeric representation of the remote port. For example,
 
 ### socket.resume()
 
+* Returns: {net.Socket} The socket itself.
+
 Resumes reading after a call to [`pause()`][].
 
 ### socket.setEncoding([encoding])
@@ -622,6 +642,8 @@ Resumes reading after a call to [`pause()`][].
 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.
 
@@ -630,6 +652,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`.
@@ -639,25 +663,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.
 
@@ -670,19 +694,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
@@ -844,6 +866,8 @@ automatically set as a listener for the [`'connection'`][] event.
 }
 ```
 
+* Returns: {net.Server}
+
 If `allowHalfOpen` is `true`, then the socket won't automatically send a FIN
 packet when the other end of the socket sends a FIN packet. The socket becomes
 non-readable, but still writable. You should call the [`end()`][] method explicitly.

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

@@ -23,7 +23,7 @@ let 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(); });
   }
 });
@@ -32,7 +32,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, () => {
+  assert.strictEqual(
-    clientLocalPorts.push(client.localPort);
+    client,
-  });
+    client.connect(server.address().port, common.localhostIPv4, () => {
+      clientLocalPorts.push(client.localPort);
+    })
+  );
 }

test/parallel/test-net-stream.js

@@ -39,7 +39,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);