From 397d5a70527719a53f9b7741bfaa0673f498f676 Mon Sep 17 00:00:00 2001 From: Sam Roberts Date: Wed, 7 Jun 2017 12:49:00 -0700 Subject: [PATCH] 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/13531 Reviewed-By: Gibson Fahnestock Reviewed-By: Colin Ihrig Reviewed-By: Luigi Pinca Reviewed-By: James M Snell --- doc/api/net.md | 56 +++++++++++++------ test/parallel/test-net-end-close.js | 2 +- test/parallel/test-net-server-close.js | 6 +- .../parallel/test-net-socket-local-address.js | 9 ++- test/parallel/test-net-stream.js | 2 +- 5 files changed, 51 insertions(+), 24 deletions(-) diff --git a/doc/api/net.md b/doc/api/net.md index d35ec06c2431be..6eb661b43af90c 100644 --- a/doc/api/net.md +++ b/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,6 +132,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. @@ -137,6 +141,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 +* 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() +* 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 +* 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 +* 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 +* 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]) +* 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]) +* 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() +* 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])