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]>

doc/api/net.markdown

@@ -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])
 
@@ -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},
@@ -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.
@@ -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.
@@ -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