Skip to content

Commit 6d26990

Browse files
Havvytellnes
authored andcommitted
doc: Clean up net.Socket
net.Socket::connect(options[, connectListener]) was missing, with the relevant details found on the net.connect function. I moved the appropriate documentation over and then rewrote the documentation for the function to say that it just creates a socket and calls the connect method on it. I also changed the other net.Socket::connect variants to say they are like the options version but called with a specific options object. net.connect and other functions were called methods even though they don't use the `this` binding, so I changed method to function where appropriate. Finally, I added a missing period to the end of the module summary. It's not really related to the rest of the changes, but benjamingr noticed it. PR-URL: #951 Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Christian Tellnes <[email protected]>
1 parent c380ac6 commit 6d26990

File tree

1 file changed

+42
-44
lines changed

1 file changed

+42
-44
lines changed

doc/api/net.markdown

+42-44
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
Stability: 2 - Stable
44

55
The `net` module provides you with an asynchronous network wrapper. It contains
6-
methods for creating both servers and clients (called streams). You can include
7-
this module with `require('net');`
6+
functions for creating both servers and clients (called streams). You can include
7+
this module with `require('net');`.
88

99
## net.createServer([options][, connectionListener])
1010

@@ -60,40 +60,17 @@ Use `nc` to connect to a UNIX domain socket server:
6060
## net.connect(options[, connectionListener])
6161
## net.createConnection(options[, connectionListener])
6262

63-
A factory method, which returns a new ['net.Socket'](#net_class_net_socket)
64-
and connects to the supplied address and port.
63+
A factory function, which returns a new ['net.Socket'](#net_class_net_socket)
64+
and automatically connects with the supplied `options`.
6565

66-
When the socket is established, the ['connect'][] event will be emitted.
67-
68-
Has the same events as ['net.Socket'](#net_class_net_socket).
69-
70-
For TCP sockets, `options` argument should be an object which specifies:
71-
72-
- `port`: Port the client should connect to (Required).
73-
74-
- `host`: Host the client should connect to. Defaults to `'localhost'`.
75-
76-
- `localAddress`: Local interface to bind to for network connections.
77-
78-
- `localPort`: Local port to bind to for network connections.
79-
80-
- `family` : Version of IP stack. Defaults to `4`.
81-
82-
For local domain sockets, `options` argument should be an object which
83-
specifies:
84-
85-
- `path`: Path the client should connect to (Required).
86-
87-
Common options are:
88-
89-
- `allowHalfOpen`: if `true`, the socket won't automatically send
90-
a FIN packet when the other end of the socket sends a FIN packet.
91-
Defaults to `false`. See ['end'][] event for more information.
66+
The options are passed to both the ['net.Socket'](#net_class_net_socket)
67+
constructor and the ['socket.connect'](#net_socket_connect_options_connectlistener)
68+
method.
9269

9370
The `connectListener` parameter will be added as an listener for the
9471
['connect'][] event.
9572

96-
Here is an example of a client of echo server as described previously:
73+
Here is an example of a client of the previously described echo server:
9774

9875
var net = require('net');
9976
var client = net.connect({port: 8124},
@@ -117,22 +94,25 @@ changed to
11794
## net.connect(port[, host][, connectListener])
11895
## net.createConnection(port[, host][, connectListener])
11996

120-
Creates a TCP connection to `port` on `host`. If `host` is omitted,
121-
`'localhost'` will be assumed.
97+
A factory function, which returns a new
98+
['net.Socket'](#net_class_net_socket) and automatically connects to the
99+
supplied `port` and `host`.
100+
101+
If `host` is omitted, `'localhost'` will be assumed.
102+
122103
The `connectListener` parameter will be added as an listener for the
123104
['connect'][] event.
124105

125-
Is a factory method which returns a new ['net.Socket'](#net_class_net_socket).
126-
127106
## net.connect(path[, connectListener])
128107
## net.createConnection(path[, connectListener])
129108

130-
Creates unix socket connection to `path`.
109+
A factory function, which returns a new unix
110+
['net.Socket'](#net_class_net_socket) and automatically connects to the
111+
supplied `path`.
112+
131113
The `connectListener` parameter will be added as an listener for the
132114
['connect'][] event.
133115

134-
A factory method which returns a new ['net.Socket'](#net_class_net_socket).
135-
136116
## Class: net.Server
137117

138118
This class is used to create a TCP or local server.
@@ -360,13 +340,26 @@ Set `readable` and/or `writable` to `true` to allow reads and/or writes on this
360340
socket (NOTE: Works only when `fd` is passed).
361341
About `allowHalfOpen`, refer to `createServer()` and `'end'` event.
362342

363-
### socket.connect(port[, host][, connectListener])
364-
### socket.connect(path[, connectListener])
343+
### socket.connect(options[, connectListener])
344+
345+
Opens the connection for a given socket.
346+
347+
For TCP sockets, `options` argument should be an object which specifies:
365348

366-
Opens the connection for a given socket. If `port` and `host` are given,
367-
then the socket will be opened as a TCP socket, if `host` is omitted,
368-
`localhost` will be assumed. If a `path` is given, the socket will be
369-
opened as a unix socket to that path.
349+
- `port`: Port the client should connect to (Required).
350+
351+
- `host`: Host the client should connect to. Defaults to `'localhost'`.
352+
353+
- `localAddress`: Local interface to bind to for network connections.
354+
355+
- `localPort`: Local port to bind to for network connections.
356+
357+
- `family` : Version of IP stack. Defaults to `4`.
358+
359+
For local domain sockets, `options` argument should be an object which
360+
specifies:
361+
362+
- `path`: Path the client should connect to (Required).
370363

371364
Normally this method is not needed, as `net.createConnection` opens the
372365
socket. Use this only if you are implementing a custom Socket.
@@ -378,6 +371,11 @@ will not be emitted, the `'error'` event will be emitted with the exception.
378371
The `connectListener` parameter will be added as an listener for the
379372
['connect'][] event.
380373

374+
### socket.connect(port[, host][, connectListener])
375+
### socket.connect(path[, connectListener])
376+
377+
As [socket.connect(options[, connectListener])](#net_socket_connect_options_connectlistener),
378+
with options either as either `{port: port, host: host}` or `{path: path}`.
381379

382380
### socket.bufferSize
383381

0 commit comments

Comments
 (0)