doc refactor: net

13 years ago · 2fd5cb3d2e
1 changed files with 49 additions and 56 deletions
--- 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(options, [cnnectionListener])
-### net.createConnection(options, [cnnectionListener])
+## net.connect(options, [cnnectionListener])
+## net.createConnection(options, [cnnectionListener])

 Constructs a new socket object and opens the socket to the given location.
 When the socket is established, the ['connect'](#event_connect_) event will be
@ -97,29 +97,27 @@ changed to

    var client = net.connect({path: '/tmp/echo.sock'},

-### net.connect(port, [host], [connectListener])
-### net.createConnection(port, [host], [connectListener])
+## 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.
 The `connectListener` parameter will be added as an listener for the
 ['connect'](#event_connect_) event.

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

 Creates unix socket connection to `path`.
 The `connectListener` parameter will be added as an listener for the
 ['connect'](#event_connect_) event.

---
-
-### 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
@ -147,7 +145,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`.

@ -156,14 +154,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([cb])
+### server.close([cb])

 Stops the server from accepting new connections. This function is
 asynchronous, the server is finally closed when the server emits a `'close'`
 event. Optionally, you can pass a callback to listen for the `'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.
@ -183,54 +181,52 @@ 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'
+### Event: 'listening'

 `function () {}`

 Emitted when the server has been bound after calling `server.listen`.

-#### Event: 'connection'
+### Event: 'connection'

 `function (socket) {}`

 Emitted when a new connection is made. `socket` is an instance of
 `net.Socket`.

-#### Event: 'close'
+### Event: 'close'

 `function () {}`

 Emitted when the server closes.

-#### Event: 'error'
+### Event: 'error'

 `function (exception) {}`

 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.

@ -245,8 +241,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,
@ -266,7 +262,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
@ -285,12 +281,12 @@ 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.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.
@ -302,7 +298,7 @@ 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.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.
@ -310,21 +306,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.
@ -338,14 +334,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.
@ -356,41 +352,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'
+### Event: 'connect'

 `function () { }`

 Emitted when a socket connection is successfully established.
 See `connect()`.

-#### Event: 'data'
+### Event: 'data'

 `function (data) { }`

@ -402,7 +398,7 @@ information.)
 Note that the __data will be lost__ if there is no listener when a `Socket`
 emits a `'data'` event.

-#### Event: 'end'
+### Event: 'end'

 `function () { }`

@ -415,7 +411,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'
+### Event: 'timeout'

 `function () { }`

@ -425,7 +421,7 @@ the socket has been idle. The user must manually close the connection.
 See also: `socket.setTimeout()`


-#### Event: 'drain'
+### Event: 'drain'

 `function () { }`

@ -433,36 +429,33 @@ 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) { }`

 Emitted when an error occurs.  The `'close'` event will be called directly
 following this event.

-#### Event: 'close'
+### Event: 'close'

 `function (had_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
+## 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.