Skip to content

Commit

Permalink
doc: Clean up net.Socket
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
Havvy authored and tellnes committed Mar 1, 2015
1 parent c380ac6 commit 6d26990
Showing 1 changed file with 42 additions and 44 deletions.
86 changes: 42 additions & 44 deletions doc/api/net.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
Stability: 2 - Stable

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

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

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

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

When the socket is established, the ['connect'][] event will be emitted.

Has the same events as ['net.Socket'](#net_class_net_socket).

For TCP sockets, `options` argument should be an object which specifies:

- `port`: Port the client should connect to (Required).

- `host`: Host the client should connect to. Defaults to `'localhost'`.

- `localAddress`: Local interface to bind to for network connections.

- `localPort`: Local port to bind to for network connections.

- `family` : Version of IP stack. Defaults to `4`.

For local domain sockets, `options` argument should be an object which
specifies:

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

Common options are:

- `allowHalfOpen`: if `true`, the socket won't automatically send
a FIN packet when the other end of the socket sends a FIN packet.
Defaults to `false`. See ['end'][] event for more information.
The options are passed to both the ['net.Socket'](#net_class_net_socket)
constructor and the ['socket.connect'](#net_socket_connect_options_connectlistener)
method.

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

Here is an example of a client of echo server as described previously:
Here is an example of a client of the previously described echo server:

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

Creates a TCP connection to `port` on `host`. If `host` is omitted,
`'localhost'` will be assumed.
A factory function, which returns a new
['net.Socket'](#net_class_net_socket) and automatically connects to the
supplied `port` and `host`.

If `host` is omitted, `'localhost'` will be assumed.

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

Is a factory method which returns a new ['net.Socket'](#net_class_net_socket).

## net.connect(path[, connectListener])
## net.createConnection(path[, connectListener])

Creates unix socket connection to `path`.
A factory function, which returns a new unix
['net.Socket'](#net_class_net_socket) and automatically connects to the
supplied `path`.

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

A factory method which returns a new ['net.Socket'](#net_class_net_socket).

## Class: net.Server

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

### socket.connect(port[, host][, connectListener])
### socket.connect(path[, connectListener])
### socket.connect(options[, connectListener])

Opens the connection for a given socket.

For TCP sockets, `options` argument should be an object which specifies:

Opens the connection for a given socket. If `port` and `host` are given,
then the socket will be opened as a TCP socket, if `host` is omitted,
`localhost` will be assumed. If a `path` is given, the socket will be
opened as a unix socket to that path.
- `port`: Port the client should connect to (Required).

- `host`: Host the client should connect to. Defaults to `'localhost'`.

- `localAddress`: Local interface to bind to for network connections.

- `localPort`: Local port to bind to for network connections.

- `family` : Version of IP stack. Defaults to `4`.

For local domain sockets, `options` argument should be an object which
specifies:

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

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

### socket.connect(port[, host][, connectListener])
### socket.connect(path[, connectListener])

As [socket.connect(options[, connectListener])](#net_socket_connect_options_connectlistener),
with options either as either `{port: port, host: host}` or `{path: path}`.

### socket.bufferSize

Expand Down

0 comments on commit 6d26990

Please sign in to comment.