From 3dd52822852d4f24478db89b47673d22c903592a Mon Sep 17 00:00:00 2001
From: Sam Roberts <vieuxtech@gmail.com>
Date: Wed, 7 Jun 2017 12:49:00 -0700
Subject: [PATCH] doc: document methods that return this

Backport of the documentation from
https://github.com/nodejs/node/pull/13531 that did not land in 2fb1381.

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 | 52 ++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 38 insertions(+), 14 deletions(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index e11f6cd627204e..bcabc98df6abc0 100644
--- a/doc/api/net.md
+++ b/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.