Various changes to Net Documentation, ammended style for API.

3 files changed, 181 insertions, 154 deletions

diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown
index 496a6118b..e0a4bf45d 100644
--- a/doc/api/_toc.markdown
+++ b/doc/api/_toc.markdown
@@ -6,14 +6,12 @@
 * [Modules](modules.html)
 * [C/C++ Addons](addons.html)
 * [Process](process.html)
-* [Constants](constants.html)
 * [Utilities](util.html)
-* [FreeList](freelist.html)
 * [Events](events.html)
 * [Buffers](buffers.html)
 * [Streams](streams.html)
 * [Crypto](crypto.html)
-	* [Secure Streams](securepair.html)
+  * [Secure Streams](securepair.html)
 * [String Decoder](string_decoder.html)
 * [File System](fs.html)
 * [Path](path.html)
@@ -29,5 +27,5 @@
 * [Child Processes](child_processes.html)
 * [Assertion Testing](assert.html)
 * Appendixes
-	* [Appendix 1: Recommended Third-party Modules](appendix_1.html)
-	* [Appendix 2: Deprecated API's](appendix_2.html)
+  * [Appendix 1: Recommended Third-party Modules](appendix_1.html)
+  * [Appendix 2: Deprecated API's](appendix_2.html)
diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index 835a8154d..a6338b0b1 100644
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -1,4 +1,32 @@
-## net.Server
+## net
+
+The `net` module provides you with an asynchronous network wrapper. It contains
+methods for creating both servers and clients (called streams).
+
+### net.createServer(connectionListener)
+
+Creates a new TCP server. The `connectionListener` argument is
+automatically set as a listener for the `'connection'` event.
+
+### net.createConnection(arguments...)
+
+Construct a new stream object and opens a stream to the given location. When
+the stream is established the `'connect'` event will be emitted.
+
+The arguments for this method change the type of connection:
+
+* `net.createConnection(port, [host])`
+
+  Creates a TCP connection to `port` on `host`. If `host` is omitted, `localhost`
+  will be assumed.
+
+* `net.createConnection(path)`
+
+  Creates unix socket connection to `path`
+
+---
+
+### net.Server
 
 This class is used to create a TCP or UNIX server.
 
@@ -28,27 +56,7 @@ changed to
 
 This is an `EventEmitter` with the following events:
 
-### Event: 'connection'
-
-`function (stream) {}`
-
-Emitted when a new connection is made. `stream` is an instance of
-`net.Stream`.
-
-### Event: 'close'
-
-`function () {}`
-
-Emitted when the server closes.
-
-
-### net.createServer(connectionListener)
-
-Creates a new TCP server. The `connectionListener` argument is
-automatically set as a listener for the `'connection'` event.
-
-
-### server.listen(port, [host], [callback])
+#### server.listen(port, [host], [callback])
 
 Begin accepting connections on the specified `port` and `host`.  If the
 `host` is omitted, the server will accept connections directed to any
@@ -57,56 +65,50 @@ IPv4 address (`INADDR_ANY`).
 This function is asynchronous. The last parameter `callback` will be called
 when the server has been bound.
 
-
-### server.listen(path, [callback])
+#### server.listen(path, [callback])
 
 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.
 
-
-### server.listenFD(fd)
+#### server.listenFD(fd)
 
 Start a server listening for connections on the given file descriptor.
 
 This file descriptor must have already had the `bind(2)` and `listen(2)` system
 calls invoked on it.
 
-### 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.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.
 
+#### Event: 'connection'
 
-## net.isIP
-
-### 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)
+`function (stream) {}`
 
-Returns true if input is a version 4 IP address, otherwise returns false.
+Emitted when a new connection is made. `stream` is an instance of
+`net.Stream`.
 
+#### Event: 'close'
 
-### net.isIPv6(input)
+`function () {}`
 
-Returns true if input is a version 6 IP address, otherwise returns false.
+Emitted when the server closes.
 
+---
 
-## net.Stream
+### net.Stream
 
 This object is an abstraction of of a TCP or UNIX socket.  `net.Stream`
 instance implement a duplex stream interface.  They can be created by the
@@ -115,181 +117,204 @@ and passed to the user through the `'connection'` event of a server.
 
 `net.Stream` instances are EventEmitters with the following events:
 
-### Event: 'connect'
+#### stream.connect(port, [host])
+#### stream.connect(path)
 
-`function () { }`
+Opens the connection for a given stream. If `port` and `host` are given,
+then the stream will be opened as a TCP stream, if `host` is omitted,
+`localhost` will be assumed. If a `path` is given, the stream will be
+opened as a unix socket to that path.
 
-Emitted when a stream connection successfully is established.
-See `connect()`.
+Normally this method is not needed, as `net.createConnection` opens the
+stream. Use this only if you are implementing a custom Stream or if a
+Stream is closed and you want to reuse it to connect to another server.
 
+This function is asynchronous. When the `'connect'` event is emitted the
+stream is established. If there is a problem connecting, the `'connect'`
+event will not be emitted, the `'error'` event will be emitted with
+the exception.
 
-### Event: 'secure'
 
-`function () { }`
+#### stream.setEncoding(encoding=null)
 
-Emitted when a stream connection successfully establishes an SSL handshake with its peer.
+Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is
+received.
 
+#### stream.setSecure([credentials])
 
-### Event: 'data'
+Enables SSL support for the stream, with the crypto module credentials specifying
+the private key and certificate of the stream, and optionally the CA certificates
+for use in peer authentication.
 
-`function (data) { }`
+If the credentials hold one ore more CA certificates, then the stream will request
+for the peer to submit a client certificate as part of the SSL connection handshake.
+The validity and content of this can be accessed via verifyPeer() and getPeerCertificate().
 
-Emitted when data is received.  The argument `data` will be a `Buffer` or
-`String`.  Encoding of data is set by `stream.setEncoding()`.
-(See the section on `Readable Stream` for more information.)
+#### stream.verifyPeer()
 
-### Event: 'end'
+Returns true or false depending on the validity of the peers's certificate in the
+context of the defined or default list of trusted CA certificates.
 
-`function () { }`
+#### stream.getPeerCertificate()
 
-Emitted when the other end of the stream sends a FIN packet. 
+Returns a JSON structure detailing the peer's certificate, containing a dictionary
+with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to'
 
-By default (`allowHalfOpen == false`) the stream will destroy its file
-descriptor  once it has written out its pending write queue.  However, by
-setting `allowHalfOpen == true` the stream will not automatically `end()`
-its side allowing the user to write arbitrary amounts of data, with the
-caviot that the user is required to `end()` thier side now. In the
-`allowHalfOpen == true` case after `'end'` is emitted the `readyState` will
-be `'writeOnly'`.
+#### stream.write(data, encoding='ascii')
 
+Sends data on the stream. The second parameter specifies the encoding in
+the case of a string--it defaults to ASCII because encoding to UTF8 is rather
+slow.
 
-### Event: 'timeout'
-
-`function () { }`
-
-Emitted if the stream times out from inactivity. This is only to notify that
-the stream has been idle. The user must manually close the connection.
-
-See also: `stream.setTimeout()`
-
+Returns `true` if the entire data was flushed successfully to the kernel
+buffer. Returns `false` if all or part of the data was queued in user memory.
+`'drain'` will be emitted when the buffer is again free.
 
-### Event: 'drain'
+#### stream.end([data], [encoding])
 
-`function () { }`
+Half-closes the stream. I.E., it sends a FIN packet. It is possible the
+server will still send some data. After calling this `readyState` will be
+`'readOnly'`.
 
-Emitted when the write buffer becomes empty. Can be used to throttle uploads.
+If `data` is specified, it is equivalent to calling `stream.write(data, encoding)`
+followed by `stream.end()`.
 
-### Event: 'error'
+#### stream.destroy()
 
-`function (exception) { }`
+Ensures that no more I/O activity happens on this stream. Only necessary in
+case of errors (parse error or so).
 
-Emitted when an error occurs.  The `'close'` event will be called directly
-following this event.
+#### stream.pause()
 
-### Event: 'close'
+Pauses the reading of data. That is, `'data'` events will not be emitted.
+Useful to throttle back an upload.
 
-`function (had_error) { }`
+#### stream.resume()
 
-Emitted once the stream is fully closed. The argument `had_error` is a boolean which says if
-the stream was closed due to a transmission
-error.
+Resumes reading after a call to `pause()`.
 
+#### stream.setTimeout(timeout)
 
-### net.createConnection(port, host='127.0.0.1')
+Sets the stream to timeout after `timeout` milliseconds of inactivity on
+the stream. By default `net.Stream` do not have a timeout.
 
-Construct a new stream object and opens a stream to the specified `port`
-and `host`. If the second parameter is omitted, localhost is assumed.
+When an idle timeout is triggered the stream will receive a `'timeout'`
+event but the connection will not be severed. The user must manually `end()`
+or `destroy()` the stream.
 
-When the stream is established the `'connect'` event will be emitted.
+If `timeout` is 0, then the existing idle timeout is disabled.
 
-### stream.connect(port, host='127.0.0.1')
+#### stream.setNoDelay(noDelay=true)
 
-Opens a stream to the specified `port` and `host`. `createConnection()`
-also opens a stream; normally this method is not needed. Use this only if
-a stream is closed and you want to reuse the object to connect to another
-server.
+Disables the Nagle algorithm. By default TCP connections use the Nagle
+algorithm, they buffer data before sending it off. Setting `noDelay` will
+immediately fire off data each time `stream.write()` is called.
 
-This function is asynchronous. When the `'connect'` event is emitted the
-stream is established. If there is a problem connecting, the `'connect'`
-event will not be emitted, the `'error'` event will be emitted with 
-the exception.
+#### stream.setKeepAlive(enable=false, [initialDelay])
 
+Enable/disable keep-alive functionality, and optionally set the initial
+delay before the first keepalive probe is sent on an idle stream.
+Set `initialDelay` (in milliseconds) to set the delay between the last
+data packet received and the first keepalive probe. Setting 0 for
+initialDelay will leave the value unchanged from the default
+(or previous) setting.
 
-### stream.remoteAddress
+#### stream.remoteAddress
 
 The string representation of the remote IP address. For example,
 `'74.125.127.100'` or `'2001:4860:a005::68'`.
 
 This member is only present in server-side connections.
 
-### stream.readyState
+#### stream.readyState
 
 Either `'closed'`, `'open'`, `'opening'`, `'readOnly'`, or `'writeOnly'`.
 
-### stream.setEncoding(encoding=null)
+#### Event: 'connect'
 
-Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is
-received.
+`function () { }`
 
-### stream.setSecure([credentials])
+Emitted when a stream connection successfully is established.
+See `connect()`.
 
-Enables SSL support for the stream, with the crypto module credentials specifying the private key and certificate of the stream, and optionally the CA certificates for use in peer authentication.
 
-If the credentials hold one ore more CA certificates, then the stream will request for the peer to submit a client certificate as part of the SSL connection handshake. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate().
+#### Event: 'secure'
 
-### stream.verifyPeer()
+`function () { }`
 
-Returns true or false depending on the validity of the peers's certificate in the context of the defined or default list of trusted CA certificates.
+Emitted when a stream connection successfully establishes an SSL handshake with its peer.
 
-### stream.getPeerCertificate()
 
-Returns a JSON structure detailing the peer's certificate, containing a dictionary with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to'
+#### Event: 'data'
 
-### stream.write(data, encoding='ascii')
+`function (data) { }`
 
-Sends data on the stream. The second parameter specifies the encoding in
-the case of a string--it defaults to ASCII because encoding to UTF8 is rather
-slow.
+Emitted when data is received.  The argument `data` will be a `Buffer` or
+`String`.  Encoding of data is set by `stream.setEncoding()`.
+(See the section on `Readable Stream` for more information.)
 
-Returns `true` if the entire data was flushed successfully to the kernel
-buffer. Returns `false` if all or part of the data was queued in user memory.
-`'drain'` will be emitted when the buffer is again free.
+#### Event: 'end'
 
-### stream.end([data], [encoding])
+`function () { }`
 
-Half-closes the stream. I.E., it sends a FIN packet. It is possible the
-server will still send some data. After calling this `readyState` will be
-`'readOnly'`.
+Emitted when the other end of the stream sends a FIN packet.
 
-If `data` is specified, it is equivalent to calling `stream.write(data, encoding)`
-followed by `stream.end()`.
+By default (`allowHalfOpen == false`) the stream will destroy its file
+descriptor  once it has written out its pending write queue.  However, by
+setting `allowHalfOpen == true` the stream will not automatically `end()`
+its side allowing the user to write arbitrary amounts of data, with the
+caveat that the user is required to `end()` their side now. In the
+`allowHalfOpen == true` case after `'end'` is emitted the `readyState` will
+be `'writeOnly'`.
 
-### stream.destroy()
 
-Ensures that no more I/O activity happens on this stream. Only necessary in
-case of errors (parse error or so).
+#### Event: 'timeout'
 
-### stream.pause()
+`function () { }`
 
-Pauses the reading of data. That is, `'data'` events will not be emitted.
-Useful to throttle back an upload.
+Emitted if the stream times out from inactivity. This is only to notify that
+the stream has been idle. The user must manually close the connection.
 
-### stream.resume()
+See also: `stream.setTimeout()`
 
-Resumes reading after a call to `pause()`.
 
-### stream.setTimeout(timeout)
+#### Event: 'drain'
 
-Sets the stream to timeout after `timeout` milliseconds of inactivity on
-the stream. By default `net.Stream` do not have a timeout.
+`function () { }`
 
-When an idle timeout is triggered the stream will receive a `'timeout'`
-event but the connection will not be severed. The user must manually `end()`
-or `destroy()` the stream.
+Emitted when the write buffer becomes empty. Can be used to throttle uploads.
 
-If `timeout` is 0, then the existing idle timeout is disabled.
+#### Event: 'error'
 
-### stream.setNoDelay(noDelay=true)
+`function (exception) { }`
 
-Disables the Nagle algorithm. By default TCP connections use the Nagle
-algorithm, they buffer data before sending it off. Setting `noDelay` will
-immediately fire off data each time `stream.write()` is called.
+Emitted when an error occurs.  The `'close'` event will be called directly
+following this event.
 
-### stream.setKeepAlive(enable=false, [initialDelay])
+#### Event: 'close'
+
+`function (had_error) { }`
+
+Emitted once the stream is fully closed. The argument `had_error` is a boolean which says if
+the stream was closed due to a transmission
+error.
+
+---
+
+### net.isIP
+
+#### 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)
+
+Returns true if input is a version 4 IP address, otherwise returns false.
+
+
+#### net.isIPv6(input)
+
+Returns true if input is a version 6 IP address, otherwise returns false.
 
-Enable/disable keep-alive functionality, and optionally set the initial
-delay before the first keepalive probe is sent on an idle stream.
-Set `initialDelay` (in milliseconds) to set the delay between the last
-data packet received and the first keepalive probe. Setting 0 for
-initialDelay will leave the value unchanged from the default
-(or previous) setting.
diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css
index a59bc5ee5..dfa9cd5c2 100644
--- a/doc/api_assets/style.css
+++ b/doc/api_assets/style.css
@@ -115,6 +115,10 @@ h4 {
   margin: 2.2em 0 1.25em;
 }
 
+h4 + h4 {
+  margin: 0 0 1.25em;
+}
+
 h5 {
   font-size: 1.125em;
   line-height: 1.4em;