diff options
author | Sam Roberts <vieuxtech@gmail.com> | 2017-06-07 12:49:00 -0700 |
---|---|---|
committer | Sam Roberts <vieuxtech@gmail.com> | 2017-06-14 13:12:21 -0700 |
commit | 84f3b8f09f273e5085394468e48b0e330b9cb888 (patch) | |
tree | 709aab970f48c9cf0aa3a30d1bfb5e983a48e875 /doc | |
parent | 3ee37329da7323a86c248a63fe20d40885c7a84a (diff) | |
download | android-node-v8-84f3b8f09f273e5085394468e48b0e330b9cb888.tar.gz android-node-v8-84f3b8f09f273e5085394468e48b0e330b9cb888.tar.bz2 android-node-v8-84f3b8f09f273e5085394468e48b0e330b9cb888.zip |
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 <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>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/net.md | 56 |
1 files changed, 40 insertions, 16 deletions
diff --git a/doc/api/net.md b/doc/api/net.md index d35ec06c24..6eb661b43a 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 <!-- 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,6 +729,8 @@ 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]) @@ -717,6 +738,8 @@ Resumes reading after a call to [`socket.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. @@ -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 |