Fix minor issues in the documentation.

doc/api.txt

@@ -6,7 +6,7 @@ Version, 0.1.26, 2010.01.20
 
 == NAME
 
-node - evented I/O for V8 javascript
+node - evented I/O for V8 JavaScript
 
 
 
@@ -39,7 +39,7 @@ Server running at http://127.0.0.1:8000/
 
 Node supports 3 string encodings. UTF-8 (+"utf8"+), ASCII (+"ascii"+), and
 Binary (+"binary"+). +"ascii"+ and +"binary"+ only look at the first 8 bits
-of the 16bit javascript string characters. Both are relatively fast--use
+of the 16bit JavaScript string characters. Both are relatively fast--use
 them if you can. +"utf8"+ is slower and should be avoided when possible.
 
 Unless otherwise noted, functions are all asynchronous and do not block
@@ -82,7 +82,7 @@ more information.
 | +"exit"+ | +code+     | Made when the process exits.
                           A listener on this event should not try to perform
                           I/O since the process will forcibly exit in less
-                          than microsecond. However, it is a good hook to
+                          than a microsecond. However, it is a good hook to
                           perform constant time checks of the module's
                           state (like for unit tests).
                           +
@@ -215,7 +215,7 @@ in a promise callback.
 ----------------------------------------
 var sys = require("sys");
 sys.exec("ls /").addCallback(function (stdout, stderr) {
-  puts(stdout);
+  sys.puts(stdout);
 });
 ----------------------------------------
 +
@@ -242,7 +242,7 @@ complete.
 
 ==== +events.EventEmitter+
 
-+require('events')+ to access the events module.
++require("events")+ to access the events module.
 
 All EventEmitters emit the event +"newListener"+ when new listeners are
 added.
@@ -261,7 +261,7 @@ Adds a listener to the end of the listeners array for the specified event.
 +
 ----------------------------------------
 server.addListener("connection", function (socket) {
-  puts("someone connected!");
+  sys.puts("someone connected!");
 });
 ----------------------------------------
 
@@ -278,9 +278,9 @@ Execute each of the listeners in order with the supplied arguments.
 
 ==== +events.Promise+
 
-+require('events')+ to access the events module.
++require("events")+ to access the events module.
 
-+events.Promise+ inherits from +process.eventEmitter+. A promise emits one of two
++events.Promise+ inherits from +process.EventEmitter+. A promise emits one of two
 events: +"success"+ or +"error"+.  After emitting its event, it will not
 emit anymore events.
 
@@ -307,7 +307,7 @@ If you created the promise (by doing +new events.Promise()+) then call
 the moment due to a bug; use +emitSuccess+ instead.)
 
 +promise.emitError(arg1, arg2, ...)+ ::
-Emits the +"error"+ event. If a no error handler is attached to the promise
+Emits the +"error"+ event. If no error handler is attached to the promise
 between +promise.emitError()+ and +process.nextTick()+, an exception is
 thrown.
 +
@@ -351,10 +351,10 @@ setTimeout(function() {
 
 +promise.timeout(timeout = undefined)+ ::
 If the +timeout+ parameter is provided, the promise will emit an +"error"+
-event after the given amount of millseconds. The timeout is canceled by any
+event after the given amount of milliseconds. The timeout is canceled by any
-+"success"+ or +"error"+ event being emitted by the Promise.
++"success"+ or +"error"+ event being emitted by the promise.
 +
-To tell apart a timeout from a regular "error" event, use the following test:
+To tell a timeout apart from a regular "error" event, use the following test:
 +
 ----------------------------------------
 promise.addErrback(function(e) {
@@ -425,7 +425,7 @@ Close stdin.
 
 === Modules
 
-Node uses the CommonJS module system
+Node uses the CommonJS module system.
 
 Node has a simple module loading system.  In Node, files and modules are in
 one-to-one correspondence.  As an example, +foo.js+ loads the module
@@ -498,14 +498,14 @@ Modules; see the section below about addons. +"index.js"+ allows one to
 package a module as a directory.
 
 +require.paths+ can be modified at runtime by simply unshifting new
-paths on to it and at startup with the +NODE_PATH+ environmental
+paths onto it, or at startup with the +NODE_PATH+ environmental
 variable (which should be a list of paths, colon separated).
 
 Use +process.mixin()+ to include modules into the global namespace.
 
 ----------------------------------------
 process.mixin(GLOBAL, require("./circle"), require("sys"));
-puts("The area of a cirlce of radius 4 is " + area(4));
+puts("The area of a circle of radius 4 is " + area(4));
 ----------------------------------------
 
 
@@ -514,8 +514,8 @@ puts("The area of a cirlce of radius 4 is " + area(4));
 === Timers
 
 
-+setTimeout(callback, delay)+::
++setTimeout(callback, delay, [arg, ...])+::
-To schedule execution of callback after delay milliseconds. Returns a
+To schedule execution of +callback+ after +delay+ milliseconds. Returns a
 +timeoutId+ for possible use with +clearTimeout()+.
 
 Optionally, you can also pass arguments to the callback.
@@ -525,8 +525,8 @@ Optionally, you can also pass arguments to the callback.
 Prevents said timeout from triggering.
 
 
-+setInterval(callback, delay)+::
++setInterval(callback, delay, [arg, ...])+::
-To schedule the repeated execution of callback every +delay+ milliseconds. Returns
+To schedule the repeated execution of +callback+ every +delay+ milliseconds. Returns
 a +intervalId+ for possible use with +clearInterval()+.
 
 Optionally, you can also pass arguments to the callback.
@@ -550,7 +550,7 @@ Node provides a tridirectional +popen(3)+ facility through the class
 
 | +"output"+ | +data+     | Each time the child process 
                             sends data to its +stdout+, this event is
-                            emitted. +data+ is a string.  + If the child
+                            emitted. +data+ is a string. If the child
                             process closes its +stdout+ stream (a common
                             thing to do on exit), this event will be emitted
                             with +data === null+.
@@ -572,7 +572,7 @@ environmental variables. For example:
 ----------------------------------------
 var ls = process.createChildProcess("ls", ["-lh", "/usr"]);
 ls.addListener("output", function (data) {
-  puts(data);
+  sys.puts(data);
 });
 ----------------------------------------
 +
@@ -654,16 +654,21 @@ sys.puts("stats: " + JSON.stringify(stats));
   - on error: no parameters.
 
 
-
 +posix.stat(path)+ ::
-  See stat(2).
+See stat(2).
-  - on success: Returns +posix.Stats+ object. It looks like this:
+- on success: Returns +posix.Stats+ object. It looks like this:
-    +{ dev: 2049, ino: 305352, mode: 16877, nlink: 12, uid: 1000, gid: 1000,
++
-    rdev: 0, size: 4096, blksize: 4096, blocks: 8, atime:
+------------------------------------------------------------------------------
-    "2009-06-29T11:11:55Z", mtime: "2009-06-29T11:11:40Z", ctime:
+  { dev: 2049, ino: 305352, mode: 16877, nlink: 12, uid: 1000, gid: 1000,
-    "2009-06-29T11:11:40Z" }+
+  rdev: 0, size: 4096, blksize: 4096, blocks: 8, atime:
-    See the +posix.Stats+ section below for more information.
+  "2009-06-29T11:11:55Z", mtime: "2009-06-29T11:11:40Z", ctime:
-  - on error: no parameters.
+  "2009-06-29T11:11:40Z" }+
+------------------------------------------------------------------------------
++
+See the +posix.Stats+ section below for more information.
+
+- on error: no parameters.
+
 
 +posix.unlink(path)+ ::
   See unlink(2)
@@ -676,11 +681,13 @@ sys.puts("stats: " + JSON.stringify(stats));
   - on success: no parameters.
   - on error: no parameters.
 
+
 +posix.mkdir(path, mode)+ ::
   See mkdir(2)
   - on success: no parameters.
   - on error: no parameters.
 
+
 +posix.readdir(path)+ ::
   Reads the contents of a directory.
   - on success: One argument, an array containing the names (strings) of the
@@ -709,25 +716,23 @@ sys.puts("stats: " + JSON.stringify(stats));
   - on error: no parameters.
 
 +posix.read(fd, length, position, encoding)+::
-
+  Read data from the file specified by +fd+.
-Read data from the file specified by +fd+.
+  +
-+
+  +length+ is an integer specifying the number of
-+length+ is an integer specifying the number of
+  bytes to read.
-bytes to read.
+  +
-+
+  +position+ is an integer specifying where to begin
-+position+ is an integer specifying where to begin
+  reading from in the file.
-reading from in the file.
+  +
-+
+  - on success: returns +data, bytes_read+, what was read from the file.
-- on success: returns +data, bytes_read+, what was read from the file.
+  - on error: no parameters.
-- on error: no parameters.
 
 +posix.cat(filename, encoding="utf8")+::
-
 Outputs the entire contents of a file. Example:
 +
 --------------------------------
 posix.cat("/etc/passwd").addCallback(function (content) {
-  puts(content);
+  sys.puts(content);
 });
 --------------------------------
 +
@@ -762,20 +767,22 @@ In particular, large, possibly chunk-encoded, messages. The interface is
 careful to never buffer entire requests or responses--the
 user is able to stream data.
 
-HTTP message headers are represented by an object like this
+HTTP message headers are represented by an object like this:
 
 ----------------------------------------
-{ "Content-Length": "123"
+{ "content-length": "123"
-, "Content-Type": "text/plain"
+, "content-type": "text/plain"
-, "Connection": "keep-alive"
+, "connection": "keep-alive"
-, "Accept": "*/*"
+, "accept": "*/*"
 }
 ----------------------------------------
 
-In order to support the full spectrum of possible HTTP applications, Node"s
+Keys are lowercased. Values are not modified.
+
+In order to support the full spectrum of possible HTTP applications, Node's
 HTTP API is very low-level. It deals with connection handling and message
 parsing only. It parses a message into headers and body but it does not
-parse the actual headers or the body. 
+parse the actual headers or the body.
 
 
 ==== +http.Server+
@@ -802,12 +809,12 @@ parse the actual headers or the body.
 
 |=========================================================
 
-+http.createServer(request_listener, options);+ ::
++http.createServer(request_listener, [options]);+ ::
 Returns a new web server object.
 +
 The +options+ argument is optional. The
 +options+ argument accepts the same values as the
-options argument for +tcp.Server+ does.
+options argument for +tcp.Server+.
 +
 The +request_listener+ is a function which is automatically
 added to the +"request"+ event.
@@ -815,12 +822,12 @@ added to the +"request"+ event.
 +server.setSecure(format_type, ca_certs, crl_list, private_key, certificate)+ ::
 Enable TLS for all incoming connections, with the specified credentials.
 +
-format_type currently has to be "X509_PEM", and each of the ca, crl, key and
++format_type+ currently has to be "X509_PEM", and each of the ca, crl, key and
 cert parameters are in the format of PEM strings. 
 +
-The ca_certs is a string that holds a number of CA certificates for use in accepting
++ca_certs+ is a string that holds a number of CA certificates for use in accepting
 client connections that authenticate themselves with a client certificate. 
-The private_key is a PEM string of the unencrypted key for the server.
++private_key+ is a PEM string of the unencrypted key for the server.
 
 +server.listen(port, hostname)+ ::
 Begin accepting connections on the specified port and hostname.
@@ -845,7 +852,7 @@ the user--and passed as the first argument to a +"request"+ listener.
                                   message body is received. Example: A chunk
                                   of the body is given as the single
                                   argument. The transfer-encoding has been
-                                  decoded.  The body chunk is a String.  The
+                                  decoded.  The body chunk is a string.  The
                                   body encoding is set with
                                   +request.setBodyEncoding()+.
 
@@ -861,7 +868,7 @@ The request method as a string. Read only. Example:
 
 +request.url+ ::
 Request URL string. This contains only the URL that is
-present in the actual HTTP request. If the request is
+present in the actual HTTP request. If the request is:
 +
 ----------------------------------------
 GET /status?name=ryan HTTP/1.1\r\n
@@ -869,7 +876,7 @@ Accept: text/plain\r\n
 \r\n
 ----------------------------------------
 +
-Then +request.url+ will be
+Then +request.url+ will be:
 +
 ----------------------------------------
 "/status?name=ryan"
@@ -915,7 +922,7 @@ The HTTP protocol version as a string. Read only. Examples:
 +"1.1"+, +"1.0"+
 
 
-+request.setBodyEncoding(encoding)+ ::
++request.setBodyEncoding(encoding="binary")+ ::
 Set the encoding for the request body. Either +"utf8"+ or +"binary"+. Defaults
 to +"binary"+.
 
@@ -940,7 +947,7 @@ passed as the second parameter to the +"request"+ event.
 +response.sendHeader(statusCode, headers)+ ::
 
 Sends a response header to the request. The status code is a 3-digit HTTP
-status code, like +404+. The second argument, +headers+ are the response headers.
+status code, like +404+. The second argument, +headers+, are the response headers.
 +
 Example:
 +
@@ -1039,11 +1046,11 @@ for the user to stream a body to the server with
 +client.setSecure(format_type, ca_certs, crl_list, private_key, certificate)+ ::
 Enable TLS for the client connection, with the specified credentials.
 +
-format_type currently has to be "X509_PEM", and each of the ca, crl, key and
++format_type+ currently has to be "X509_PEM", and each of the ca, crl, key and
 cert parameters are in the format of PEM strings, and optional.
 +
-The ca_certs is a string that holds a number of CA certificates for use in deciding the
++ca_certs+ is a string that holds a number of CA certificates for use in deciding the
-authenticity of the remote server. The private_key is a PEM string of the unencrypted
+authenticity of the remote server. +private_key+ is a PEM string of the unencrypted
 key for the client, which together with the certificate allows the client to authenticate
 itself to the server.
 
@@ -1098,7 +1105,7 @@ argument which is an instance of +http.ClientResponse+.
 +
 In the +responseListener+ callback, one can add more listeners to the
 response, in particular listening for the +"body"+ event. Note that
-the +responseListener+ is called before any part of the body is receieved,
+the +responseListener+ is called before any part of the body is received,
 so there is no need to worry about racing to catch the first part of the
 body. As long as a listener for +"body"+ is added during the
 +responseListener+ callback, the entire body will be caught.
@@ -1107,7 +1114,7 @@ body. As long as a listener for +"body"+ is added during the
 // Good
 request.finish(function (response) {
   response.addListener("body", function (chunk) {
-    puts("BODY: " + chunk);
+    sys.puts("BODY: " + chunk);
   });
 });
 
@@ -1115,7 +1122,7 @@ request.finish(function (response) {
 request.finish(function (response) {
   setTimeout(function () {
     response.addListener("body", function (chunk) {
-      puts("BODY: " + chunk);
+      sys.puts("BODY: " + chunk);
     });
   }, 10);
 });
@@ -1244,7 +1251,7 @@ To use the TCP server and client one must +require("tcp")+.
 ==== +tcp.Server+
 
 Here is an example of a echo server which listens for connections
-on port 7000
+on port 7000:
 
 ----------------------------------------
 var tcp = require("tcp");
@@ -1285,12 +1292,12 @@ the +"connection"+ event.
 +server.setSecure(format_type, ca_certs, crl_list, private_key, certificate)+ ::
 Enable TLS for all incoming connections, with the specified credentials.
 +
-format_type currently has to be "X509_PEM", and each of the ca, crl, key and
++format_type+ currently has to be "X509_PEM", and each of the ca, crl, key and
 cert parameters are in the format of PEM strings. 
 +
-The ca_certs is a string that holds a number of CA certificates for use in accepting
++ca_certs+ is a string that holds a number of CA certificates for use in accepting
 client connections that authenticate themselves with a client certificate. 
-The private_key is a PEM string of the unencrypted key for the server.
++private_key+ is a PEM string of the unencrypted key for the server.
 
 +server.listen(port, host=null, backlog=128)+ ::
 Tells the server to listen for TCP connections to +port+ and +host+.
@@ -1430,35 +1437,36 @@ in RFC2253. This function is synchronous.
 
 === DNS module
 
-Use +require("dns")+ to access this module
+Use +require("dns")+ to access this module.
 
-Here is an example of which resolves +"www.google.com"+ then reverse
+Here is an example which resolves +"www.google.com"+ then reverse
 resolves the IP addresses which are returned.
 
 -------------------------------------------------------------------------
-var dns = require("dns");
+var dns = require("dns"),
+    sys = require("sys");
 
 var resolution = dns.resolve4("www.google.com");
 
 resolution.addCallback(function (addresses, ttl, cname) {
-  puts("addresses: " + JSON.stringify(addresses));
+  sys.puts("addresses: " + JSON.stringify(addresses));
-  puts("ttl: " + JSON.stringify(ttl));
+  sys.puts("ttl: " + JSON.stringify(ttl));
-  puts("cname: " + JSON.stringify(cname));
+  sys.puts("cname: " + JSON.stringify(cname));
 
   for (var i = 0; i < addresses.length; i++) {
     var a = addresses[i];
     var reversing = dns.reverse(a);
     reversing.addCallback( function (domains, ttl, cname) {
-      puts("reverse for " + a + ": " + JSON.stringify(domains));
+      sys.puts("reverse for " + a + ": " + JSON.stringify(domains));
     });
     reversing.addErrback( function (code, msg) {
-      puts("reverse for " + a + " failed: " + msg);
+      sys.puts("reverse for " + a + " failed: " + msg);
     });
   }
 });
 
 resolution.addErrback(function (code, msg) {
-  puts("error: " + msg);
+  sys.puts("error: " + msg);
 });
 -------------------------------------------------------------------------
 
@@ -1521,10 +1529,10 @@ Tests for deep equality.
 Tests for any deep inequality. 
 
 +assert.strictEqual(actual, expected, message)+::
-Tests strict equality, as determined by bitwise equality operator ( +===+ ) 
+Tests strict equality, as determined by the strict equality operator ( +===+ ) 
 
 +assert.notStrictEqual(actual, expected, message)+::
-Tests strict non-equality, as determined by bitwise not equal operator ( +!==+ ) 
+Tests strict non-equality, as determined by the strict not equal operator ( +!==+ ) 
 
 +assert.throws(block, error, message)+::
 Expects +block+ to throw an error.
@@ -1536,7 +1544,7 @@ Expects +block+ not to throw an error.
 === Path Module
 
 This module contains utilities for dealing with file paths.  Use
-+require('path')+ to use it.  It provides the following methods:
++require("path")+ to use it.  It provides the following methods:
 
 +path.join(/* path1, path2, ... */)+::
 Join all arguments together and resolve the resulting path.  Example:
@@ -1584,9 +1592,9 @@ node> require("path").dirname("/foo/bar/baz/asdf/quux")
 Return the last portion of a path.  Similar to the Unix +basename+ command.  Example:
 +
 ------------------------------------
-node> require("path").filename("/foo/bar/baz/asdf/quux.html")
+node> require("path").basename("/foo/bar/baz/asdf/quux.html")
 "quux.html"
-node> require("path").filename("/foo/bar/baz/asdf/quux.html", ".html")
+node> require("path").basename("/foo/bar/baz/asdf/quux.html", ".html")
 "quux"
 ------------------------------------
 +
@@ -1653,7 +1661,7 @@ Either the "params" portion of the query string, or a querystring-parsed object.
 +"query=string"+ or +{"query":"string"}+
 
 +hash+::
-The portion of the URL after the pound-sign.  Example: +"#hash"+
+The "fragment" portion of the URL including the pound-sign. Example: +"#hash"+
 
 The following methods are provided by the URL module:
 
@@ -1700,10 +1708,10 @@ node> require("querystring").parse("foo=bar&baz%5Bquux%5D=asdf&baz%5Boof%5D=rab&
 ------------------------------------
 +
 
-+querystring.escape+
++querystring.escape+::
 The escape function used by +querystring.stringify+, provided so that it could be overridden if necessary.
 
-+querystring.unescape+
++querystring.unescape+::
 The unescape function used by +querystring.parse+, provided so that it could be overridden if necessary.
 
 == REPL
@@ -1749,7 +1757,7 @@ Addons are dynamically linked shared objects. They can provide glue to C and
 C++ libraries. The API (at the moment) is rather complex, involving
 knowledge of several libraries:
 
- - V8 Javascript, a C++ library. Used for interfacing with Javascript:
+ - V8 JavaScript, a C++ library. Used for interfacing with JavaScript:
    creating objects, calling functions, etc.  Documented mostly in the
    +v8.h+ header file (+deps/v8/include/v8.h+ in the Node source tree).