docs: typos and minor edits in several modules

tshinnic · bnoordhuis · commit 4cf0ce5bb4c2 · 2011-09-06T18:19:41.000+02:00
Mostly quite minor edits.  Those possibly of more interest are:

  emitter.setMaxListeners(n)

    That the limit is per event name for an emitter.

  fs.readlink()

    Not a path, but rather the symbolic link's string value, which
      would be at best a partial path, certainly not a 'resolvedPath'

  global.__filename

    This may be "well-known" but this is a full path to the module
    that referencing code is running in.  It is not the main program's
    path, unless you are in the main program.  Each module knows only
    its own path.

  server.listen(port,...)

    I actually needed this functionality... "gimme just _any_ next port"

  stream.end()
  stream.destroy()

    Yeah, everybody knows what happens to the queued data, but let's
    make it *really* explicit for the first readers.
diff --git a/doc/api/events.markdown b/doc/api/events.markdown
@@ -35,8 +35,8 @@ Adds a listener to the end of the listeners array for the specified event.
 
 #### emitter.once(event, listener)
 
-Adds a **one time** listener for the event. The listener is
-invoked only the first time the event is fired, after which
+Adds a **one time** listener for the event. This listener is
+invoked only the next time the event is fired, after which
 it is removed.
 
     server.once('connection', function (stream) {
@@ -64,7 +64,7 @@ Removes all listeners, or those of the specified event.
 #### emitter.setMaxListeners(n)
 
 By default EventEmitters will print a warning if more than 10 listeners are
-added to it. This is a useful default which helps finding memory leaks.
+added for a particular event. This is a useful default which helps finding memory leaks.
 Obviously not all Emitters should be limited to 10. This function allows
 that to be increased. Set to zero for unlimited.
 
@@ -77,7 +77,7 @@ manipulated, e.g. to remove listeners.
     server.on('connection', function (stream) {
       console.log('someone connected!');
     });
-    console.log(util.inspect(server.listeners('connection')); // [ [Function] ]
+    console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
 
 #### emitter.emit(event, [arg1], [arg2], [...])
 
diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
@@ -9,6 +9,9 @@ The arguments passed to the completion callback depend on the method, but the
 first argument is always reserved for an exception. If the operation was
 completed successfully, then the first argument will be `null` or `undefined`.
 
+When using the synchronous form any exceptions are immediately thrown.
+You can use try/catch to handle exceptions or allow them to bubble up.
+
 Here is an example of the asynchronous version:
 
     var fs = require('fs');
@@ -75,7 +78,7 @@ Synchronous ftruncate(2).
 
 ### fs.chown(path, uid, gid, [callback])
 
-Asycnronous chown(2). No arguments other than a possible exception are given
+Asynchronous chown(2). No arguments other than a possible exception are given
 to the completion callback.
 
 ### fs.chownSync(path, uid, gid)
@@ -84,7 +87,7 @@ Synchronous chown(2).
 
 ### fs.fchown(path, uid, gid, [callback])
 
-Asycnronous fchown(2). No arguments other than a possible exception are given
+Asynchronous fchown(2). No arguments other than a possible exception are given
 to the completion callback.
 
 ### fs.fchownSync(path, uid, gid)
@@ -93,7 +96,7 @@ Synchronous fchown(2).
 
 ### fs.lchown(path, uid, gid, [callback])
 
-Asycnronous lchown(2). No arguments other than a possible exception are given
+Asynchronous lchown(2). No arguments other than a possible exception are given
 to the completion callback.
 
 ### fs.lchownSync(path, uid, gid)
@@ -194,16 +197,16 @@ Synchronous symlink(2).
 ### fs.readlink(path, [callback])
 
 Asynchronous readlink(2). The callback gets two arguments `(err,
-resolvedPath)`.
+linkString)`.
 
 ### fs.readlinkSync(path)
 
-Synchronous readlink(2). Returns the resolved path.
+Synchronous readlink(2). Returns the symbolic link's string value.
 
 ### fs.realpath(path, [callback])
 
 Asynchronous realpath(2).  The callback gets two arguments `(err,
-resolvedPath)`.
+resolvedPath)`.  May use `process.cwd` to resolve relative paths.
 
 ### fs.realpathSync(path)
 
@@ -316,7 +319,7 @@ current position.
 See pwrite(2).
 
 The callback will be given three arguments `(err, written, buffer)` where `written`
-specifies how many _bytes_ were written into `buffer`.
+specifies how many _bytes_ were written from `buffer`.
 
 Note that it is unsafe to use `fs.write` multiple times on the same file
 without waiting for the callback. For this scenario,
@@ -329,7 +332,7 @@ written.
 
 ### fs.writeSync(fd, str, position, encoding='utf8')
 
-Synchronous version of string-based `fs.write()`. Returns the number of bytes
+Synchronous version of string-based `fs.write()`. Returns the number of _bytes_
 written.
 
 ### fs.read(fd, buffer, offset, length, position, [callback])
diff --git a/doc/api/globals.markdown b/doc/api/globals.markdown
@@ -1,6 +1,6 @@
 ## Global Objects
 
-These object are available in all modules. Some of these objects aren't
+These objects are available in all modules. Some of these objects aren't
 actually in the global scope but in the module scope - this will be noted.
 
 ### global
@@ -43,8 +43,10 @@ value from this object, the next `require` will reload the module.
 
 ### __filename
 
-The filename of the script being executed.  This is the absolute path, and not necessarily
-the same filename passed in as a command line argument.
+The filename of the code being executed.  This is the resolved absolute path
+of this code file.  For a main program this is not necessarily the same
+filename used in the command line.  The value inside a module is the path
+to that module file.
 
 Example: running `node example.js` from `/Users/mjr`
 
@@ -55,7 +57,7 @@ Example: running `node example.js` from `/Users/mjr`
 
 ### __dirname
 
-The dirname of the script being executed.
+The name of the directory that the currently executing script resides in.
 
 Example: running `node example.js` from `/Users/mjr`
 
diff --git a/doc/api/http.markdown b/doc/api/http.markdown
@@ -31,7 +31,7 @@ This is an `EventEmitter` with the following events:
 
 `function (request, response) { }`
 
-Emitted each time there is request. Note that there may be multiple requests
+Emitted each time there is a request. Note that there may be multiple requests
 per connection (in the case of keep-alive connections).
  `request` is an instance of `http.ServerRequest` and `response` is
  an instance of `http.ServerResponse`
@@ -302,7 +302,7 @@ status code which was sent out.
 ### response.setHeader(name, value)
 
 Sets a single header value for implicit headers.  If this header already exists
-in the to-be-sent headers, it's value will be replaced.  Use an array of strings
+in the to-be-sent headers, its value will be replaced.  Use an array of strings
 here if you need to send multiple headers with the same name.
 
 Example:
diff --git a/doc/api/net.markdown b/doc/api/net.markdown
@@ -35,13 +35,14 @@ The arguments for this method change the type of connection:
 
   Creates unix socket connection to `path`
 
-The `callback` parameter will be added as an listener for the 'connect` event.
+The `callback` parameter will be added as an listener for the `'connect'` event.
 
 ---
 
 ### 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.
 
 Here is an example of a echo server which listens for connections
 on port 8124:
@@ -66,20 +67,18 @@ Use `nc` to connect to a UNIX domain socket server:
 
     nc -U /tmp/echo.sock
 
-`net.Server` is an `EventEmitter` with the following events:
-
 #### 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
-IPv4 address (`INADDR_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.
 
-One issue some users run into is getting `EADDRINUSE` errors. Meaning
+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
-would be to wait a second and the try again. This can be done with
+would be to wait a second and then try again. This can be done with
 
     server.on('error', function (e) {
       if (e.code == 'EADDRINUSE') {
@@ -149,6 +148,15 @@ Set this property to reject connections when the server's connection count gets
 
 The number of concurrent connections on the server.
 
+
+`net.Server` is an `EventEmitter` with the following events:
+
+#### Event: 'listening'
+
+`function () {}`
+
+Emitted when the server has been bound after calling `server.listen`.
+
 #### Event: 'connection'
 
 `function (socket) {}`
@@ -162,17 +170,22 @@ Emitted when a new connection is made. `socket` is an instance of
 
 Emitted when the server closes.
 
+#### 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
 
-This object is an abstraction of of a TCP or UNIX socket.  `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.
 
-`net.Socket` instances are EventEmitters with the following events:
-
 #### new net.Socket([options])
 
 Construct a new socket object.
@@ -212,7 +225,7 @@ event.
 #### socket.bufferSize
 
 `net.Socket` has the property that `socket.write()` always works. This is to
-help users get up an running quickly. The computer cannot necessarily keep up
+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
@@ -225,7 +238,7 @@ written, but the buffer may contain strings, and the strings are lazily
 encoded, so the exact number of bytes is not known.)
 
 Users who experience large or growing `bufferSize` should attempt to
-"throttle" the data flows in their program with `pause()` and resume()`.
+"throttle" the data flows in their program with `pause()` and `resume()`.
 
 
 #### socket.setEncoding(encoding=null)
@@ -260,7 +273,7 @@ event on the other end.
 
 #### socket.end([data], [encoding])
 
-Half-closes the socket. I.E., it sends a FIN packet. It is possible the
+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)`
@@ -332,12 +345,13 @@ The amount of received bytes.
 The amount of bytes sent.
 
 
+`net.Socket` instances are EventEmitters with the following events:
 
 #### Event: 'connect'
 
 `function () { }`
 
-Emitted when a socket connection successfully is established.
+Emitted when a socket connection is successfully established.
 See `connect()`.
 
 #### Event: 'data'
@@ -377,6 +391,8 @@ See also: `socket.setTimeout()`
 
 Emitted when the write buffer becomes empty. Can be used to throttle uploads.
 
+See also: the return values of `socket.write()`
+
 #### Event: 'error'
 
 `function (exception) { }`
diff --git a/doc/api/path.markdown b/doc/api/path.markdown
@@ -1,13 +1,19 @@
 ## Path
 
-This module contains utilities for dealing with file paths.  Use
-`require('path')` to use it.  It provides the following methods:
+This module contains utilities for handling and transforming file
+paths.  Almost all these methods perform only string transformations.
+The file system is not consulted to check whether paths are valid.
+
+`path.exists` and `path.existsSync` are the exceptions, and should
+logically be found in the fs module as they do access the file system.
+
+Use `require('path')` to use this module.  The following methods are provided:
 
 ### path.normalize(p)
 
 Normalize a string path, taking care of `'..'` and `'.'` parts.
 
-When multiple slashes are found, they're replaces by a single one;
+When multiple slashes are found, they're replaced by a single one;
 when the path contains a trailing slash, it is preserved.
 On windows backslashes are used. 
 
@@ -75,8 +81,9 @@ Examples:
 
 Solve the relative path from `from` to `to`.
 
-Sometimes we've got two absolute pathes, and we need to calculate the relative path from one to another.
-It's accually the reverse transform of path.resolve, which means we assume:
+At times we have two absolute paths, and we need to derive the relative
+path from one to the other.  This is actually the reverse transform of
+`path.resolve`, which means we see that:
 
     path.resolve(from, path.relative(from, to)) == path.resolve(to)
 
@@ -116,22 +123,27 @@ Example:
 
 ### path.extname(p)
 
-Return the extension of the path.  Everything after the last '.' in the last portion
-of the path.  If there is no '.' in the last portion of the path or the only '.' is
-the first character, then it returns an empty string.  Examples:
+Return the extension of the path, from the last '.' to end of string
+in the last portion of the path.  If there is no '.' in the last portion
+of the path or the first character of it is '.', then it returns
+an empty string.  Examples:
 
     path.extname('index.html')
     // returns
     '.html'
 
+    path.extname('index.')
+    // returns
+    '.'
+
     path.extname('index')
     // returns
     ''
 
 ### path.exists(p, [callback])
 
-Test whether or not the given path exists.  Then, call the `callback` argument
-with either true or false. Example:
+Test whether or not the given path exists by checking with the file system.
+Then call the `callback` argument with either true or false.  Example:
 
     path.exists('/etc/passwd', function (exists) {
       util.debug(exists ? "it's there" : "no passwd!");
diff --git a/doc/api/stdio.markdown b/doc/api/stdio.markdown
@@ -1,6 +1,8 @@
 ## console
 
-Browser-like object for printing to stdout and stderr.
+For printing to stdout and stderr.  Similar to the console object functions
+provided by most web browsers, here the output is sent to stdout or stderr.
+
 
 ### console.log()
 
diff --git a/doc/api/streams.markdown b/doc/api/streams.markdown
@@ -112,7 +112,7 @@ A `Writable Stream` has the following methods, members, and events.
 
 `function () { }`
 
-Emitted after a `write()` method was called that returned `false` to
+After a `write()` method returned `false`, this event is emitted to
 indicate that it is safe to write again.
 
 ### Event: 'error'
@@ -159,6 +159,7 @@ Same as the above except with a raw buffer.
 ### stream.end()
 
 Terminates the stream with EOF or FIN.
+This call will allow queued write data to be sent before closing the stream.
 
 ### stream.end(string, encoding)
 
@@ -172,6 +173,7 @@ Same as above but with a `buffer`.
 ### stream.destroy()
 
 Closes the underlying file descriptor. Stream will not emit any more events.
+Any queued write data will not be sent.
 
 ### stream.destroySoon()
 
diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown
