Skip to content

Commit 59eb761

Browse files
sam-githubMylesBorins
authored andcommitted
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: #13553 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Roman Reiss <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 34fc7a0 commit 59eb761

5 files changed

+49
-22
lines changed

doc/api/net.md

+38-14
Original file line numberDiff line numberDiff line change
@@ -89,13 +89,17 @@ Don't call `server.address()` until the `'listening'` event has been emitted.
8989
added: v0.1.90
9090
-->
9191

92+
* Returns: {net.Server}
93+
9294
Stops the server from accepting new connections and keeps existing
9395
connections. This function is asynchronous, the server is finally
9496
closed when all connections are ended and the server emits a [`'close'`][] event.
9597
The optional `callback` will be called once the `'close'` event occurs. Unlike
9698
that event, it will be called with an Error as its only argument if the server
9799
was not open when it was closed.
98100

101+
Returns `server`.
102+
99103
### server.connections
100104
<!-- YAML
101105
added: v0.2.0
@@ -128,6 +132,7 @@ added: v0.5.10
128132
* `handle` {Object}
129133
* `backlog` {number}
130134
* `callback` {Function}
135+
* Returns: {net.Server}
131136

132137
The `handle` object can be set to either a server or socket (anything
133138
with an underlying `_handle` member), or a `{fd: <n>}` object.
@@ -158,6 +163,7 @@ added: v0.11.14
158163
* `path` {string} - Optional.
159164
* `exclusive` {boolean} - Optional.
160165
* `callback` {Function} - Optional.
166+
* Returns: {net.Server}
161167

162168
The `port`, `host`, and `backlog` properties of `options`, as well as the
163169
optional callback function, behave as they do on a call to
@@ -189,6 +195,7 @@ added: v0.1.90
189195
* `path` {string}
190196
* `backlog` {number}
191197
* `callback` {Function}
198+
* Returns: {net.Server}
192199

193200
Start a local socket server listening for connections on the given `path`.
194201

@@ -227,6 +234,7 @@ subsequent call will *re-open* the server using the provided options.
227234
<!-- YAML
228235
added: v0.1.90
229236
-->
237+
* Returns: {net.Server}
230238

231239
Begin accepting connections on the specified `port` and `hostname`. If the
232240
`hostname` is omitted, the server will accept connections on any IPv6 address
@@ -289,23 +297,23 @@ with [`child_process.fork()`][].
289297
added: v0.9.1
290298
-->
291299

300+
* Returns: {net.Server}
301+
292302
Opposite of `unref`, calling `ref` on a previously `unref`d server will *not*
293303
let the program exit if it's the only server left (the default behavior). If
294304
the server is `ref`d calling `ref` again will have no effect.
295305

296-
Returns `server`.
297-
298306
### server.unref()
299307
<!-- YAML
300308
added: v0.9.1
301309
-->
302310

311+
* Returns: {net.Server}
312+
303313
Calling `unref` on a server will allow the program to exit if this is the only
304314
active server in the event system. If the server is already `unref`d calling
305315
`unref` again will have no effect.
306316

307-
Returns `server`.
308-
309317
## Class: net.Socket
310318
<!-- YAML
311319
added: v0.3.4
@@ -501,6 +509,10 @@ specifies:
501509

502510
- `path`: Path the client should connect to (Required).
503511

512+
For either case:
513+
514+
* Returns: {net.Socket} The socket itself.
515+
504516
Normally this method is not needed, as `net.createConnection` opens the
505517
socket. Use this only if you are implementing a custom Socket.
506518

@@ -520,6 +532,8 @@ added: v0.1.90
520532
As [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`],
521533
with options as either `{port: port, host: host}` or `{path: path}`.
522534

535+
* Returns: {net.Socket} The socket itself.
536+
523537
### socket.connecting
524538
<!-- YAML
525539
added: v6.1.0
@@ -550,6 +564,8 @@ connection is destroyed no further data can be transferred using it.
550564
added: v0.1.90
551565
-->
552566

567+
* Returns: {net.Socket} The socket itself.
568+
553569
Half-closes the socket. i.e., it sends a FIN packet. It is possible the
554570
server will still send some data.
555571

@@ -575,6 +591,8 @@ The numeric representation of the local port. For example,
575591

576592
### socket.pause()
577593

594+
* Returns: {net.Socket} The socket itself.
595+
578596
Pauses the reading of data. That is, [`'data'`][] events will not be emitted.
579597
Useful to throttle back an upload.
580598

@@ -583,12 +601,12 @@ Useful to throttle back an upload.
583601
added: v0.9.1
584602
-->
585603

604+
* Returns: {net.Socket} The socket itself.
605+
586606
Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not*
587607
let the program exit if it's the only socket left (the default behavior). If
588608
the socket is `ref`d calling `ref` again will have no effect.
589609

590-
Returns `socket`.
591-
592610
### socket.remoteAddress
593611
<!-- YAML
594612
added: v0.5.10
@@ -615,13 +633,17 @@ The numeric representation of the remote port. For example,
615633

616634
### socket.resume()
617635

636+
* Returns: {net.Socket} The socket itself.
637+
618638
Resumes reading after a call to [`pause()`][].
619639

620640
### socket.setEncoding([encoding])
621641
<!-- YAML
622642
added: v0.1.90
623643
-->
624644

645+
* Returns: {net.Socket} The socket itself.
646+
625647
Set the encoding for the socket as a [Readable Stream][]. See
626648
[`stream.setEncoding()`][] for more information.
627649

@@ -630,6 +652,8 @@ Set the encoding for the socket as a [Readable Stream][]. See
630652
added: v0.1.92
631653
-->
632654

655+
* Returns: {net.Socket} The socket itself.
656+
633657
Enable/disable keep-alive functionality, and optionally set the initial
634658
delay before the first keepalive probe is sent on an idle socket.
635659
`enable` defaults to `false`.
@@ -639,25 +663,25 @@ data packet received and the first keepalive probe. Setting 0 for
639663
initialDelay will leave the value unchanged from the default
640664
(or previous) setting. Defaults to `0`.
641665

642-
Returns `socket`.
643-
644666
### socket.setNoDelay([noDelay])
645667
<!-- YAML
646668
added: v0.1.90
647669
-->
648670

671+
* Returns: {net.Socket} The socket itself.
672+
649673
Disables the Nagle algorithm. By default TCP connections use the Nagle
650674
algorithm, they buffer data before sending it off. Setting `true` for
651675
`noDelay` will immediately fire off data each time `socket.write()` is called.
652676
`noDelay` defaults to `true`.
653677

654-
Returns `socket`.
655-
656678
### socket.setTimeout(timeout[, callback])
657679
<!-- YAML
658680
added: v0.1.90
659681
-->
660682

683+
* Returns: {net.Socket} The socket itself.
684+
661685
Sets the socket to timeout after `timeout` milliseconds of inactivity on
662686
the socket. By default `net.Socket` do not have a timeout.
663687

@@ -670,19 +694,17 @@ If `timeout` is 0, then the existing idle timeout is disabled.
670694
The optional `callback` parameter will be added as a one time listener for the
671695
[`'timeout'`][] event.
672696

673-
Returns `socket`.
674-
675697
### socket.unref()
676698
<!-- YAML
677699
added: v0.9.1
678700
-->
679701

702+
* Returns: {net.Socket} The socket itself.
703+
680704
Calling `unref` on a socket will allow the program to exit if this is the only
681705
active socket in the event system. If the socket is already `unref`d calling
682706
`unref` again will have no effect.
683707

684-
Returns `socket`.
685-
686708
### socket.write(data[, encoding][, callback])
687709
<!-- YAML
688710
added: v0.1.90
@@ -844,6 +866,8 @@ automatically set as a listener for the [`'connection'`][] event.
844866
}
845867
```
846868

869+
* Returns: {net.Server}
870+
847871
If `allowHalfOpen` is `true`, then the socket won't automatically send a FIN
848872
packet when the other end of the socket sends a FIN packet. The socket becomes
849873
non-readable, but still writable. You should call the [`end()`][] method explicitly.

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ const s = new net.Socket({
1414
},
1515
writable: false
1616
});
17-
s.resume();
17+
assert.strictEqual(s, s.resume());
1818

1919
const events = [];
2020

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

+3-3
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ let server = net.createServer(function(c) {
2323
sockets.push(c);
2424

2525
if (sockets.length === 2) {
26-
server.close();
26+
assert.strictEqual(server.close(), server);
2727
sockets.forEach(function(c) { c.destroy(); });
2828
}
2929
});
@@ -32,7 +32,7 @@ server.on('close', function() {
3232
events.push('server');
3333
});
3434

35-
server.listen(0, function() {
35+
assert.strictEqual(server, server.listen(0, function() {
3636
net.createConnection(this.address().port);
3737
net.createConnection(this.address().port);
38-
});
38+
}));

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

+6-3
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,10 @@ function connect() {
3434

3535
conns++;
3636
client.once('close', connect);
37-
client.connect(server.address().port, common.localhostIPv4, () => {
38-
clientLocalPorts.push(client.localPort);
39-
});
37+
assert.strictEqual(
38+
client,
39+
client.connect(server.address().port, common.localhostIPv4, () => {
40+
clientLocalPorts.push(client.localPort);
41+
})
42+
);
4043
}

test/parallel/test-net-stream.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ const server = net.createServer(function(socket) {
3939
}).listen(0, function() {
4040
const conn = net.connect(this.address().port);
4141
conn.on('data', function(buf) {
42-
conn.pause();
42+
assert.strictEqual(conn, conn.pause());
4343
setTimeout(function() {
4444
conn.destroy();
4545
}, 20);

0 commit comments

Comments
 (0)