doc refactor: net

1 files changed, 51 insertions, 71 deletions

diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index 49cf5b049ce..d3c2bff8b44 100644
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -1,10 +1,10 @@
-## net
+# net
 
 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');`
 
-### net.createServer([options], [connectionListener])
+## net.createServer([options], [connectionListener])
 
 Creates a new TCP server. The `connectionListener` argument is
 automatically set as a listener for the ['connection'](#event_connection_)
@@ -49,8 +49,8 @@ Use `nc` to connect to a UNIX domain socket server:
 
     nc -U /tmp/echo.sock
 
-### net.connect(arguments...)
-### net.createConnection(arguments...)
+## net.connect(arguments...)
+## net.createConnection(arguments...)
 
 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
@@ -92,14 +92,12 @@ changed to
 
     var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
 
----
-
-### net.Server
+## Class: net.Server
 
 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])
+### 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
@@ -127,7 +125,7 @@ would be to wait a second and then try again. This can be done with
 (Note: All sockets in Node set `SO_REUSEADDR` already)
 
 
-#### server.listen(path, [listeningListener])
+### server.listen(path, [listeningListener])
 
 Start a UNIX socket server listening for connections on the given `path`.
 
@@ -136,14 +134,14 @@ This function is asynchronous.  When the server has been bound,
 the last parameter `listeningListener` will be added as an listener for the
 ['listening'](#event_listening_) event.
 
-#### server.close()
+### server.close()
 
 Stops the server from accepting new connections. This function is
 asynchronous, the server is finally closed when the server emits a `'close'`
 event.
 
 
-#### server.address()
+### server.address()
 
 Returns the bound address and port of the server as reported by the operating system.
 Useful to find which port was assigned when giving getting an OS-assigned address.
@@ -163,54 +161,48 @@ Example:
 
 Don't call `server.address()` until the `'listening'` event has been emitted.
 
-#### server.maxConnections
+### server.maxConnections
 
 Set this property to reject connections when the server's connection count gets
 high.
 
-#### server.connections
+### server.connections
 
 The number of concurrent connections on the server.
 
 
 `net.Server` is an `EventEmitter` with the following events:
 
-#### Event: 'listening'
-
-`function () {}`
+### Event: 'listening'
 
 Emitted when the server has been bound after calling `server.listen`.
 
-#### Event: 'connection'
+### Event: 'connection'
 
-`function (socket) {}`
+* {Socket object} The connection object
 
 Emitted when a new connection is made. `socket` is an instance of
 `net.Socket`.
 
-#### Event: 'close'
-
-`function () {}`
+### Event: 'close'
 
 Emitted when the server closes.
 
-#### Event: 'error'
+### Event: 'error'
 
-`function (exception) {}`
+* {Error Object}
 
 Emitted when an error occurs.  The `'close'` event will be called directly
 following this event.  See example in discussion of `server.listen`.
 
----
-
-### net.Socket
+## Class: net.Socket
 
 This object is an abstraction of a TCP or UNIX socket.  `net.Socket`
 instances implement a duplex Stream interface.  They can be created by the
 user and used as a client (with `connect()`) or they can be created by Node
 and passed to the user through the `'connection'` event of a server.
 
-#### new net.Socket([options])
+### new net.Socket([options])
 
 Construct a new socket object.
 
@@ -225,8 +217,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], [connectListener])
-#### socket.connect(path, [connectListener])
+### 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,
@@ -246,7 +238,7 @@ The `connectListener` parameter will be added as an listener for the
 ['connect'](#event_connect_) event.
 
 
-#### socket.bufferSize
+### 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
@@ -265,18 +257,18 @@ Users who experience large or growing `bufferSize` should attempt to
 "throttle" the data flows in their program with `pause()` and `resume()`.
 
 
-#### socket.setEncoding([encoding])
+### socket.setEncoding([encoding])
 
 Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is
 received. Defaults to `null`.
 
-#### socket.setSecure()
+### socket.setSecure()
 
 This function has been removed in v0.3. It used to upgrade the connection to
 SSL/TLS. See the [TLS section](tls.html#tLS_) for the new API.
 
 
-#### socket.write(data, [encoding], [callback])
+### socket.write(data, [encoding], [callback])
 
 Sends data on the socket. The second parameter specifies the encoding in the
 case of a string--it defaults to UTF8 encoding.
@@ -288,12 +280,12 @@ buffer. Returns `false` if all or part of the data was queued in user memory.
 The optional `callback` parameter will be executed when the data is finally
 written out - this may not be immediately.
 
-#### socket.write(data, [encoding], [callback])
+### socket.write(data, [encoding], [callback])
 
 Write data with the optional encoding. The callback will be made when the
 data is flushed to the kernel.
 
-#### socket.end([data], [encoding])
+### socket.end([data], [encoding])
 
 Half-closes the socket. i.e., it sends a FIN packet. It is possible the
 server will still send some data.
@@ -301,21 +293,21 @@ server will still send some data.
 If `data` is specified, it is equivalent to calling
 `socket.write(data, encoding)` followed by `socket.end()`.
 
-#### socket.destroy()
+### socket.destroy()
 
 Ensures that no more I/O activity happens on this socket. Only necessary in
 case of errors (parse error or so).
 
-#### socket.pause()
+### socket.pause()
 
 Pauses the reading of data. That is, `'data'` events will not be emitted.
 Useful to throttle back an upload.
 
-#### socket.resume()
+### socket.resume()
 
 Resumes reading after a call to `pause()`.
 
-#### socket.setTimeout(timeout, [callback])
+### socket.setTimeout(timeout, [callback])
 
 Sets the socket to timeout after `timeout` milliseconds of inactivity on
 the socket. By default `net.Socket` do not have a timeout.
@@ -329,14 +321,14 @@ 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.
 
-#### socket.setNoDelay([noDelay])
+### socket.setNoDelay([noDelay])
 
 Disables the Nagle algorithm. By default TCP connections use the Nagle
 algorithm, they buffer data before sending it off. Setting `true` for
 `noDelay` will immediately fire off data each time `socket.write()` is called.
 `noDelay` defaults to `true`.
 
-#### socket.setKeepAlive([enable], [initialDelay])
+### socket.setKeepAlive([enable], [initialDelay])
 
 Enable/disable keep-alive functionality, and optionally set the initial
 delay before the first keepalive probe is sent on an idle socket.
@@ -347,43 +339,41 @@ data packet received and the first keepalive probe. Setting 0 for
 initialDelay will leave the value unchanged from the default
 (or previous) setting. Defaults to `0`.
 
-#### socket.address()
+### 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}`
 
-#### socket.remoteAddress
+### socket.remoteAddress
 
 The string representation of the remote IP address. For example,
 `'74.125.127.100'` or `'2001:4860:a005::68'`.
 
-#### socket.remotePort
+### socket.remotePort
 
 The numeric representation of the remote port. For example,
 `80` or `21`.
 
-#### socket.bytesRead
+### socket.bytesRead
 
 The amount of received bytes.
 
-#### socket.bytesWritten
+### socket.bytesWritten
 
 The amount of bytes sent.
 
 
 `net.Socket` instances are EventEmitters with the following events:
 
-#### Event: 'connect'
-
-`function () { }`
+### Event: 'connect'
 
 Emitted when a socket connection is successfully established.
 See `connect()`.
 
-#### Event: 'data'
+### Event: 'data'
 
-`function (data) { }`
+* {Buffer object}
 
 Emitted when data is received.  The argument `data` will be a `Buffer` or
 `String`.  Encoding of data is set by `socket.setEncoding()`.
@@ -393,9 +383,7 @@ information.)
 Note that the __data will be lost__ if there is no listener when a `Socket`
 emits a `'data'` event.
 
-#### Event: 'end'
-
-`function () { }`
+### Event: 'end'
 
 Emitted when the other end of the socket sends a FIN packet.
 
@@ -406,9 +394,7 @@ its side allowing the user to write arbitrary amounts of data, with the
 caveat that the user is required to `end()` their side now.
 
 
-#### Event: 'timeout'
-
-`function () { }`
+### Event: 'timeout'
 
 Emitted if the socket times out from inactivity. This is only to notify that
 the socket has been idle. The user must manually close the connection.
@@ -416,44 +402,38 @@ the socket has been idle. The user must manually close the connection.
 See also: `socket.setTimeout()`
 
 
-#### Event: 'drain'
-
-`function () { }`
+### Event: 'drain'
 
 Emitted when the write buffer becomes empty. Can be used to throttle uploads.
 
 See also: the return values of `socket.write()`
 
-#### Event: 'error'
+### Event: 'error'
 
-`function (exception) { }`
+* {Error object}
 
 Emitted when an error occurs.  The `'close'` event will be called directly
 following this event.
 
-#### Event: 'close'
+### Event: 'close'
 
-`function (had_error) { }`
+* `had_error` {Boolean} true if the socket had a transmission error
 
 Emitted once the socket is fully closed. The argument `had_error` is a boolean
 which says if the socket was closed due to a transmission error.
 
----
-
-### net.isIP
-
-#### net.isIP(input)
+## net.isIP(input)
 
 Tests if input is an IP address. Returns 0 for invalid strings,
 returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.
 
 
-#### net.isIPv4(input)
+## net.isIPv4(input)
 
 Returns true if input is a version 4 IP address, otherwise returns false.
 
 
-#### net.isIPv6(input)
+## net.isIPv6(input)
 
 Returns true if input is a version 6 IP address, otherwise returns false.