docs: add example to net.connect()

Fixes #1824.

diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index a6e9f8f..1f40842 100644 (file)
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -2,12 +2,13 @@
 
 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");`
+this module with `require('net');`
 
 ### net.createServer([options], [connectionListener])
 
 Creates a new TCP server. The `connectionListener` argument is
-automatically set as a listener for the `'connection'` event.
+automatically set as a listener for the ['connection'](#event_connection_)
+event.
 
 `options` is an object with the following defaults:
 
@@ -16,65 +17,98 @@ automatically set as a listener for the `'connection'` event.
 
 If `allowHalfOpen` is `true`, then the socket won't automatically send FIN
 packet when the other end of the socket sends a FIN packet. The socket becomes
-non-readable, but still writable. You should call the end() method explicitly.
-See `'end'` event for more information.
+non-readable, but still writable. You should call the `end()` method explicitly.
+See ['end'](#event_end_) event for more information.
 
-### net.createConnection(arguments...)
+Here is an example of a echo server which listens for connections
+on port 8124:
 
-Construct a new socket object and opens a socket to the given location. When
-the socket is established the `'connect'` event will be emitted.
+    var net = require('net');
+    var server = net.createServer(function(c) { //'connection' listener
+      console.log('server connected');
+      c.on('end', function() {
+        console.log('server disconnected');
+      });
+      c.write('hello\r\n');
+      c.pipe(c);
+    });
+    server.listen(8124, function() { //'listening' listener
+      console.log('server bound');
+    });
 
-The arguments for this method change the type of connection:
+Test this by using `telnet`:
 
-* `net.createConnection(port, [host], [callback])`
+    telnet localhost 8124
 
-  Creates a TCP connection to `port` on `host`. If `host` is omitted,
-  `localhost` will be assumed.
+To listen on the socket `/tmp/echo.sock` the third line from the last would
+just be changed to
 
-* `net.createConnection(path, [callback])`
+    server.listen('/tmp/echo.sock', function() { //'listening' listener
 
-  Creates unix socket connection to `path`
+Use `nc` to connect to a UNIX domain socket server:
 
-The `callback` parameter will be added as an listener for the `'connect'` event.
+    nc -U /tmp/echo.sock
 
----
+### net.connect(arguments...)
+### net.createConnection(arguments...)
 
-### net.Server
+Construct a new socket object and opens a socket to the given location. When
+the socket is established the ['connect'](#event_connect_) event will be
+emitted.
 
-This class is used to create a TCP or UNIX server.
-A server is a `net.Socket` that can listen for new incoming connections.
+The arguments for these methods change the type of connection:
 
-Here is an example of a echo server which listens for connections
-on port 8124:
+* `net.connect(port, [host], [connectListener])`
+* `net.createConnection(port, [host], [connectListener])`
 
-    var net = require('net');
-    var server = net.createServer(function (c) {
-      c.write('hello\r\n');
-      c.pipe(c);
-    });
-    server.listen(8124, 'localhost');
+  Creates a TCP connection to `port` on `host`. If `host` is omitted,
+  `'localhost'` will be assumed.
 
-Test this by using `telnet`:
+* `net.connect(path, [connectListener])`
+* `net.createConnection(path, [connectListener])`
 
-    telnet localhost 8124
+  Creates unix socket connection to `path`.
+
+The `connectListener` parameter will be added as an listener for the
+['connect'](#event_connect_) event.
+
+Here is an example of a client of echo server as described previously:
+
+    var net = require('net');
+    var client = net.connect(8124, function() { //'connect' listener
+      console.log('client connected');
+      client.write('world!\r\n');
+    });
+    client.on('data', function(data) {
+      console.log(data.toString());
+      client.end();
+    });
+    client.on('end', function() {
+      console.log('client disconnected');
+    });
 
-To listen on the socket `/tmp/echo.sock` the last line would just be
+To connect on the socket `/tmp/echo.sock` the second line would just be
 changed to
 
-    server.listen('/tmp/echo.sock');
+    var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
 
-Use `nc` to connect to a UNIX domain socket server:
+---
 
-    nc -U /tmp/echo.sock
+### net.Server
 
-#### server.listen(port, [host], [callback])
+This class is used to create a TCP or UNIX server.
+A server is a `net.Socket` that can listen for new incoming connections.
+
+#### server.listen(port, [host], [listeningListener])
 
 Begin accepting connections on the specified `port` and `host`.  If the
 `host` is omitted, the server will accept connections directed to any
 IPv4 address (`INADDR_ANY`). A port value of zero will assign a random port.
 
-This function is asynchronous. The last parameter `callback` will be called
-when the server has been bound.
+This function is asynchronous.  When the server has been bound,
+['listening'](#event_listening_) event will be emitted.
+the last parameter `listeningListener` will be added as an listener for the
+['listening'](#event_listening_) event.
 
 One issue some users run into is getting `EADDRINUSE` errors. This means that
 another server is already running on the requested port. One way of handling this
@@ -90,15 +124,16 @@ would be to wait a second and then try again. This can be done with
       }
     });
 
-(Note: All sockets in Node are set SO_REUSEADDR already)
+(Note: All sockets in Node set `SO_REUSEADDR` already)
 
 
-#### server.listen(path, [callback])
+#### server.listen(path, [listeningListener])
 
 Start a UNIX socket server listening for connections on the given `path`.
 
-This function is asynchronous. The last parameter `callback` will be called
-when the server has been bound.
+This function is asynchronous. The last parameter `listeningListener` will be
+called when the server has been bound.
+See also ['listening'](#event_listening_) event.
 
 #### server.listenFD(fd)
 
@@ -142,7 +177,8 @@ Example:
 
 #### server.maxConnections
 
-Set this property to reject connections when the server's connection count gets high.
+Set this property to reject connections when the server's connection count gets
+high.
 
 #### server.connections
 
@@ -201,8 +237,8 @@ Construct a new socket object.
 specified underlying protocol. It can be `'tcp4'`, `'tcp6'`, or `'unix'`.
 About `allowHalfOpen`, refer to `createServer()` and `'end'` event.
 
-#### socket.connect(port, [host], [callback])
-#### socket.connect(path, [callback])
+#### socket.connect(port, [host], [connectListener])
+#### socket.connect(path, [connectListener])
 
 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,
@@ -213,23 +249,23 @@ Normally this method is not needed, as `net.createConnection` opens the
 socket. Use this only if you are implementing a custom Socket or if a
 Socket is closed and you want to reuse it to connect to another server.
 
-This function is asynchronous. When the `'connect'` event is emitted the
-socket is established. If there is a problem connecting, the `'connect'`
-event will not be emitted, the `'error'` event will be emitted with
+This function is asynchronous. When the ['connect'](#event_connect_) event is
+emitted the socket is established. If there is a problem connecting, the
+`'connect'` event will not be emitted, the `'error'` event will be emitted with
 the exception.
 
-The `callback` parameter will be added as an listener for the 'connect'
-event.
+The `connectListener` parameter will be added as an listener for the
+['connect'](#event_connect_) event.
 
 
 #### socket.bufferSize
 
 `net.Socket` has the property that `socket.write()` always works. This is to
 help users get up and running quickly. The computer cannot always keep up
-with the amount of data that is written to a socket - the network connection simply
-might be too slow. Node will internally queue up the data written to a socket and
-send it out over the wire when it is possible. (Internally it is polling on
-the socket's file descriptor for being writable).
+with the amount of data that is written to a socket - the network connection
+simply might be too slow. Node will internally queue up the data written to a
+socket and send it out over the wire when it is possible. (Internally it is
+polling on the socket's file descriptor for being writable).
 
 The consequence of this internal buffering is that memory may grow. This
 property shows the number of characters currently buffered to be written.
@@ -276,8 +312,8 @@ event on the other end.
 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()`.
+If `data` is specified, it is equivalent to calling
+`socket.write(data, encoding)` followed by `socket.end()`.
 
 #### socket.destroy()
 
@@ -304,7 +340,8 @@ or `destroy()` the socket.
 
 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.
+The optional `callback` parameter will be added as a one time listener for the
+`'timeout'` event.
 
 #### socket.setNoDelay(noDelay=true)
 
@@ -323,8 +360,9 @@ initialDelay will leave the value unchanged from the default
 
 #### socket.address()
 
-Returns the bound address and port of the socket as reported by the operating system.
-Returns an object with two properties, e.g. `{"address":"192.168.57.1", "port":62053}`
+Returns the bound address and port of the socket as reported by the operating
+system. Returns an object with two properties, e.g.
+`{"address":"192.168.57.1", "port":62053}`
 
 #### socket.remoteAddress
 
@@ -360,7 +398,8 @@ See `connect()`.
 
 Emitted when data is received.  The argument `data` will be a `Buffer` or
 `String`.  Encoding of data is set by `socket.setEncoding()`.
-(See the [Readable Stream](streams.html#readable_Stream) section for more information.)
+(See the [Readable Stream](streams.html#readable_Stream) section for more
+information.)
 
 #### Event: 'end'