From: Silas Sewell Date: Sun, 21 Nov 2010 22:22:34 +0000 (-0500) Subject: Various doc tweaks (2-spaces vs tabs, EOL-whitespace, repl prompt, "world" vs "World... X-Git-Tag: v0.3.2~192 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=11b2ee76322c2d251d618ece286d23272ca92af5;p=platform%2Fupstream%2Fnodejs.git Various doc tweaks (2-spaces vs tabs, EOL-whitespace, repl prompt, "world" vs "World", etc...) --- diff --git a/doc/api/addons.markdown b/doc/api/addons.markdown index 29e4402..115bd07 100644 --- a/doc/api/addons.markdown +++ b/doc/api/addons.markdown @@ -40,10 +40,10 @@ To get started we create a file `hello.cc`: using namespace v8; extern "C" void - init (Handle target) + init (Handle target) { HandleScope scope; - target->Set(String::New("hello"), String::New("World")); + target->Set(String::New("hello"), String::New("world")); } This source code needs to be built into `hello.node`, the binary Addon. To diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown index 389fce2..e651144 100644 --- a/doc/api/assert.markdown +++ b/doc/api/assert.markdown @@ -13,7 +13,7 @@ Tests if value is a `true` value, it is equivalent to `assert.equal(true, value, ### assert.equal(actual, expected, [message]) -Tests shallow, coercive equality with the equal comparison operator ( `==` ). +Tests shallow, coercive equality with the equal comparison operator ( `==` ). ### assert.notEqual(actual, expected, [message]) @@ -25,15 +25,15 @@ Tests for deep equality. ### assert.notDeepEqual(actual, expected, [message]) -Tests for any deep inequality. +Tests for any deep inequality. ### assert.strictEqual(actual, expected, [message]) -Tests strict equality, as determined by the strict equality operator ( `===` ) +Tests strict equality, as determined by the strict equality operator ( `===` ) ### assert.notStrictEqual(actual, expected, [message]) -Tests strict non-equality, as determined by the strict not equal operator ( `!==` ) +Tests strict non-equality, as determined by the strict not equal operator ( `!==` ) ### assert.throws(block, [error], [message]) diff --git a/doc/api/buffers.markdown b/doc/api/buffers.markdown index 33fbed5..782f601 100644 --- a/doc/api/buffers.markdown +++ b/doc/api/buffers.markdown @@ -53,7 +53,7 @@ Example: write a utf8 string into a buffer, then print it console.log(len + " bytes: " + buf.toString('utf8', 0, len)); // 12 bytes: ½ + ¼ = ¾ - + ### buffer.toString(encoding, start=0, end=buffer.length) @@ -84,7 +84,7 @@ Example: copy an ASCII string into a buffer, one byte at a time: ### Buffer.byteLength(string, encoding='utf8') -Gives the actual byte length of a string. This is not the same as +Gives the actual byte length of a string. This is not the same as `String.prototype.length` since that returns the number of *characters* in a string. @@ -101,7 +101,7 @@ Example: ### buffer.length The size of the buffer in bytes. Note that this is not necessarily the size -of the contents. `length` refers to the amount of memory allocated for the +of the contents. `length` refers to the amount of memory allocated for the buffer object. It does not change when the contents of the buffer are changed. buf = new Buffer(1234); @@ -122,7 +122,7 @@ into `buf2`, starting at the 8th byte in `buf2`. buf1 = new Buffer(26); buf2 = new Buffer(26); - + for (var i = 0 ; i < 26 ; i++) { buf1[i] = i + 97; // 97 is ASCII a buf2[i] = 33; // ASCII ! @@ -132,7 +132,7 @@ into `buf2`, starting at the 8th byte in `buf2`. console.log(buf2.toString('ascii', 0, 25)); // !!!!!!!!qrst!!!!!!!!!!!!! - + ### buffer.slice(start, end=buffer.length) diff --git a/doc/api/child_processes.markdown b/doc/api/child_processes.markdown index 2b67993..efbadb0 100644 --- a/doc/api/child_processes.markdown +++ b/doc/api/child_processes.markdown @@ -145,7 +145,7 @@ output, and return it all in a callback. exec = require('child_process').exec, child; - child = exec('cat *.js bad_file | wc -l', + child = exec('cat *.js bad_file | wc -l', function (error, stdout, stderr) { console.log('stdout: ' + stdout); console.log('stderr: ' + stderr); diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index 6b18d65..a125fa8 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -1,6 +1,6 @@ ## dgram -Datagram sockets are available through `require('dgram')`. Datagrams are most commonly +Datagram sockets are available through `require('dgram')`. Datagrams are most commonly handled as IP/UDP messages, but they can also be used over Unix domain sockets. ### Event: 'message' @@ -27,7 +27,7 @@ on this socket. ### dgram.createSocket(type, [callback]) Creates a datagram socket of the specified types. Valid types are: -`udp4`, `udp6`, and `unix_dgram`. +`udp4`, `udp6`, and `unix_dgram`. Takes an optional callback which is added as a listener for `message` events. @@ -35,7 +35,7 @@ Takes an optional callback which is added as a listener for `message` events. For Unix domain datagram sockets, the destination address is a pathname in the filesystem. An optional callback may be supplied that is invoked after the `sendto` call is completed -by the OS. It is not safe to re-use `buf` until the callback is invoked. Note that +by the OS. It is not safe to re-use `buf` until the callback is invoked. Note that unless the socket is bound to a pathname with `bind()` there is no way to receive messages on this socket. @@ -55,7 +55,7 @@ Example of sending a message to syslogd on OSX via Unix domain socket `/var/run/ ### dgram.send(buf, offset, length, port, address, [callback]) For UDP sockets, the destination port and IP address must be specified. A string -may be supplied for the `address` parameter, and it will be resolved with DNS. An +may be supplied for the `address` parameter, and it will be resolved with DNS. An optional callback may be specified to detect any DNS errors and when `buf` may be re-used. Note that DNS lookups will delay the time that a send takes place, at least until the next tick. The only way to know for sure that a send has taken place @@ -143,12 +143,12 @@ Example of a UDP server listening on port 41234: ### dgram.close() -Close the underlying socket and stop listening for data on it. UDP sockets +Close the underlying socket and stop listening for data on it. UDP sockets automatically listen for messages, even if they did not call `bind()`. ### dgram.address() -Returns an object containing the address information for a socket. For UDP sockets, +Returns an object containing the address information for a socket. For UDP sockets, this object will contain `address` and `port`. For Unix domain sockets, it will contain only `address`. @@ -160,9 +160,9 @@ may be sent to a local interface's broadcast address. ### dgram.setTTL(ttl) Sets the `IP_TTL` socket option. TTL stands for "Time to Live," but in this context it -specifies the number of IP hops that a packet is allowed to go through. Each router or +specifies the number of IP hops that a packet is allowed to go through. Each router or gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a -router, it will not be forwarded. Changing TTL values is typically done for network +router, it will not be forwarded. Changing TTL values is typically done for network probes or when multicasting. The argument to `setTTL()` is a number of hops between 1 and 255. The default on most diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index b55f93d..fc97655 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -54,8 +54,8 @@ the error in English. ### dns.resolve4(domain, callback) -The same as `dns.resolve()`, but only for IPv4 queries (`A` records). -`addresses` is an array of IPv4 addresses (e.g. +The same as `dns.resolve()`, but only for IPv4 queries (`A` records). +`addresses` is an array of IPv4 addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). ### dns.resolve6(domain, callback) @@ -80,14 +80,14 @@ The same as `dns.resolve()`, but only for text queries (`TXT` records). The same as `dns.resolve()`, but only for service records (`SRV` records). `addresses` is an array of the SRV records available for `domain`. Properties -of SRV records are priority, weight, port, and name (e.g., +of SRV records are priority, weight, port, and name (e.g., `[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]`). ### dns.reverse(ip, callback) Reverse resolves an ip address to an array of domain names. -The callback has arguments `(err, domains)`. +The callback has arguments `(err, domains)`. If there an an error, `err` will be non-null and an instanceof the Error object. diff --git a/doc/api/events.markdown b/doc/api/events.markdown index 85715a7..e069559 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -1,11 +1,11 @@ ## Events Many objects in Node emit events: a `net.Server` emits an event each time -a peer connects to it, a `fs.readStream` emits an event when the file is +a peer connects to it, a `fs.readStream` emits an event when the file is opened. All objects which emit events are instances of `events.EventEmitter`. You can access this module by doing: `require("events");` -Typically, event names are represented by a camel-cased string, however, +Typically, event names are represented by a camel-cased string, however, there aren't any strict restrictions on that, as any string will be accepted. Functions can be then be attached to objects, to be executed when an event @@ -16,9 +16,9 @@ is emitted. These functions are called _listeners_. To access the EventEmitter class, `require('events').EventEmitter`. -When an `EventEmitter` instance experiences an error, the typical action is +When an `EventEmitter` instance experiences an error, the typical action is to emit an `'error'` event. Error events are treated as a special case in node. -If there is no listener for it, then the default action is to print a stack +If there is no listener for it, then the default action is to print a stack trace and exit the program. All EventEmitters emit the event `'newListener'` when new listeners are @@ -29,9 +29,9 @@ added. Adds a listener to the end of the listeners array for the specified event. - server.on('connection', function (stream) { - console.log('someone connected!'); - }); + server.on('connection', function (stream) { + console.log('someone connected!'); + }); #### emitter.once(event, listener) @@ -39,21 +39,21 @@ Adds a **one time** listener for the event. The listener is invoked only the first time the event is fired, after which it is removed. - server.once('connection', function (stream) { - console.log('Ah, we have our first user!'); - }); + server.once('connection', function (stream) { + console.log('Ah, we have our first user!'); + }); #### emitter.removeListener(event, listener) Remove a listener from the listener array for the specified event. **Caution**: changes array indices in the listener array behind the listener. - var callback = function(stream) { - console.log('someone connected!'); - }; - server.on('connection', callback); - // ... - server.removeListener('connection', callback); + var callback = function(stream) { + console.log('someone connected!'); + }; + server.on('connection', callback); + // ... + server.removeListener('connection', callback); #### emitter.removeAllListeners(event) @@ -66,10 +66,10 @@ Removes all listeners from the listener array for the specified event. Returns an array of listeners for the specified event. This array can be manipulated, e.g. to remove listeners. - server.on('connection', function (stream) { - console.log('someone connected!'); - }); - console.log(util.inspect(server.listeners('connection')); // [ [Function] ] + server.on('connection', function (stream) { + console.log('someone connected!'); + }); + 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 index 4433801..802cb0c 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -2,7 +2,7 @@ File I/O is provided by simple wrappers around standard POSIX functions. To use this module do `require('fs')`. All the methods have asynchronous and -synchronous forms. +synchronous forms. The asynchronous form always take a completion callback as its last argument. The arguments passed to the completion callback depend on the method, but the @@ -54,7 +54,7 @@ the entire process until they complete--halting all connections. ### fs.rename(path1, path2, [callback]) -Asynchronous rename(2). No arguments other than a possible exception are given +Asynchronous rename(2). No arguments other than a possible exception are given to the completion callback. ### fs.renameSync(path1, path2) @@ -63,7 +63,7 @@ Synchronous rename(2). ### fs.truncate(fd, len, [callback]) -Asynchronous ftruncate(2). No arguments other than a possible exception are +Asynchronous ftruncate(2). No arguments other than a possible exception are given to the completion callback. ### fs.truncateSync(fd, len) @@ -72,16 +72,16 @@ Synchronous ftruncate(2). ### fs.chmod(path, mode, [callback]) -Asynchronous chmod(2). No arguments other than a possible exception are given +Asynchronous chmod(2). No arguments other than a possible exception are given to the completion callback. ### fs.chmodSync(path, mode) Synchronous chmod(2). - + ### fs.stat(path, [callback]) -Asynchronous stat(2). The callback gets two arguments `(err, stats)` where +Asynchronous stat(2). The callback gets two arguments `(err, stats)` where `stats` is a `fs.Stats` object. It looks like this: { dev: 2049, @@ -102,14 +102,14 @@ See the `fs.Stats` section below for more information. ### fs.lstat(path, [callback]) -Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where -`stats` is a `fs.Stats` object. lstat() is identical to stat(), except that if -path is a symbolic link, then the link itself is stat-ed, not the file that it +Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where +`stats` is a `fs.Stats` object. lstat() is identical to stat(), except that if +path is a symbolic link, then the link itself is stat-ed, not the file that it refers to. ### fs.fstat(fd, [callback]) -Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where +Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where `stats` is a `fs.Stats` object. ### fs.statSync(path) @@ -126,7 +126,7 @@ Synchronous fstat(2). Returns an instance of `fs.Stats`. ### fs.link(srcpath, dstpath, [callback]) -Asynchronous link(2). No arguments other than a possible exception are given to +Asynchronous link(2). No arguments other than a possible exception are given to the completion callback. ### fs.linkSync(dstpath, srcpath) @@ -135,7 +135,7 @@ Synchronous link(2). ### fs.symlink(linkdata, path, [callback]) -Asynchronous symlink(2). No arguments other than a possible exception are given +Asynchronous symlink(2). No arguments other than a possible exception are given to the completion callback. ### fs.symlinkSync(linkdata, path) @@ -144,8 +144,8 @@ Synchronous symlink(2). ### fs.readlink(path, [callback]) -Asynchronous readlink(2). The callback gets two arguments `(err, -resolvedPath)`. +Asynchronous readlink(2). The callback gets two arguments `(err, +resolvedPath)`. ### fs.readlinkSync(path) @@ -153,7 +153,7 @@ Synchronous readlink(2). Returns the resolved path. ### fs.realpath(path, [callback]) -Asynchronous realpath(2). The callback gets two arguments `(err, +Asynchronous realpath(2). The callback gets two arguments `(err, resolvedPath)`. ### fs.realpathSync(path) @@ -162,7 +162,7 @@ Synchronous realpath(2). Returns the resolved path. ### fs.unlink(path, [callback]) -Asynchronous unlink(2). No arguments other than a possible exception are given +Asynchronous unlink(2). No arguments other than a possible exception are given to the completion callback. ### fs.unlinkSync(path) @@ -171,7 +171,7 @@ Synchronous unlink(2). ### fs.rmdir(path, [callback]) -Asynchronous rmdir(2). No arguments other than a possible exception are given +Asynchronous rmdir(2). No arguments other than a possible exception are given to the completion callback. ### fs.rmdirSync(path) @@ -180,7 +180,7 @@ Synchronous rmdir(2). ### fs.mkdir(path, mode, [callback]) -Asynchronous mkdir(2). No arguments other than a possible exception are given +Asynchronous mkdir(2). No arguments other than a possible exception are given to the completion callback. ### fs.mkdirSync(path, mode) @@ -200,7 +200,7 @@ Synchronous readdir(3). Returns an array of filenames excluding `'.'` and ### fs.close(fd, [callback]) -Asynchronous close(2). No arguments other than a possible exception are given +Asynchronous close(2). No arguments other than a possible exception are given to the completion callback. ### fs.closeSync(fd) @@ -210,11 +210,11 @@ Synchronous close(2). ### fs.open(path, flags, mode=0666, [callback]) Asynchronous file open. See open(2). Flags can be 'r', 'r+', 'w', 'w+', 'a', -or 'a+'. The callback gets two arguments `(err, fd)`. +or 'a+'. The callback gets two arguments `(err, fd)`. ### fs.openSync(path, flags, mode=0666) -Synchronous open(2). +Synchronous open(2). ### fs.write(fd, buffer, offset, length, position, [callback]) @@ -232,12 +232,12 @@ specifies how many _bytes_ were written. ### fs.writeSync(fd, buffer, offset, length, position) -Synchronous version of buffer-based `fs.write()`. Returns the number of bytes +Synchronous version of buffer-based `fs.write()`. Returns the number of bytes 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]) @@ -257,12 +257,12 @@ The callback is given the two arguments, `(err, bytesRead)`. ### fs.readSync(fd, buffer, offset, length, position) -Synchronous version of buffer-based `fs.read`. Returns the number of +Synchronous version of buffer-based `fs.read`. Returns the number of `bytesRead`. ### fs.readSync(fd, length, position, encoding) -Synchronous version of string-based `fs.read`. Returns the number of +Synchronous version of string-based `fs.read`. Returns the number of `bytesRead`. ### fs.readFile(filename, [encoding], [callback]) @@ -320,7 +320,7 @@ stat object: console.log('the previous mtime was: ' + prev.mtime); }); -These stat objects are instances of `fs.Stat`. +These stat objects are instances of `fs.Stat`. ### fs.unwatchFile(filename) diff --git a/doc/api/http.markdown b/doc/api/http.markdown index 95a581f..c61c544 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -47,7 +47,7 @@ This is an `EventEmitter` with the following events: `function (errno) { }` - Emitted when the server closes. + Emitted when the server closes. ### Event: 'request' @@ -284,9 +284,9 @@ first chunk of body. ### response.addTrailers(headers) This method adds HTTP trailing headers (a header but at the end of the -message) to the response. +message) to the response. -Trailers will **only** be emitted if chunked encoding is used for the +Trailers will **only** be emitted if chunked encoding is used for the response; if it is not (e.g., if the request was HTTP/1.0), they will be silently discarded. @@ -345,7 +345,7 @@ There are a few special headers that should be noted. * Sending a 'Content-length' header will disable the default chunked encoding. -* Sending an 'Expect' header will immediately send the request headers. +* Sending an 'Expect' header will immediately send the request headers. Usually, when sending 'Expect: 100-continue', you should both set a timeout and listen for the `continue` event. See RFC2616 Section 8.2.3 for more information. diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown index 89efa6e..2e135d7 100644 --- a/doc/api/modules.markdown +++ b/doc/api/modules.markdown @@ -8,7 +8,7 @@ variable with the same name as the module. Example: var util = require('util'); - + It is possible to extend node with other modules. See `'Modules'` ## Modules @@ -53,7 +53,7 @@ That is, `circle.js` must be in the same directory as `foo.js` for Without the leading `'./'`, like `require('assert')` the module is searched for in the `require.paths` array. `require.paths` on my system looks like -this: +this: `[ '/home/ryan/.node_modules' ]` diff --git a/doc/api/net.markdown b/doc/api/net.markdown index c37a2dc..62947d6 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -1,7 +1,7 @@ ## 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 +methods for creating both servers and clients (called streams). You can include this module with `require("net");` ### net.createServer(connectionListener) diff --git a/doc/api/path.markdown b/doc/api/path.markdown index 2e0c9e0..cc3dc6d 100644 --- a/doc/api/path.markdown +++ b/doc/api/path.markdown @@ -19,7 +19,7 @@ Normalize an array of path parts, taking care of `'..'` and `'.'` parts. Example: - path.normalizeArray(['', + path.normalizeArray(['', 'foo', 'bar', 'baz', 'asdf', 'quux', '..']) // returns [ '', 'foo', 'bar', 'baz', 'asdf' ] @@ -65,7 +65,7 @@ of the path. If there is no '.' in the last portion of the path or the only '.' the first character, then it returns an empty string. Examples: path.extname('index.html') - // returns + // returns '.html' path.extname('index') diff --git a/doc/api/process.markdown b/doc/api/process.markdown index 8094dcf..5fee9a1 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -158,7 +158,7 @@ An object containing the user environment. See environ(7). ### process.exit(code=0) -Ends the process with the specified `code`. If omitted, exit uses the +Ends the process with the specified `code`. If omitted, exit uses the 'success' code `0`. To exit with a 'failure' code: @@ -194,7 +194,7 @@ blocks while resolving it to a numerical ID. ### process.getuid() -Gets the user identity of the process. (See getuid(2).) +Gets the user identity of the process. (See getuid(2).) This is the numerical userid, not the username. console.log('Current uid: ' + process.getuid()); diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown index 0bc5c16..8ae3623 100644 --- a/doc/api/repl.markdown +++ b/doc/api/repl.markdown @@ -10,9 +10,9 @@ dropped into the REPL. It has simplistic emacs line-editing. mjr:~$ node Type '.help' for options. - node> a = [ 1, 2, 3]; + > a = [ 1, 2, 3]; [ 1, 2, 3 ] - node> a.forEach(function (v) { + > a.forEach(function (v) { ... console.log(v); ... }); 1 @@ -27,10 +27,10 @@ For example, you could add this to your bashrc file: alias node="env NODE_NO_READLINE=1 rlwrap node" -### repl.start(prompt='node> ', stream=process.openStdin()) +### repl.start(prompt='> ', stream=process.openStdin()) Starts a REPL with `prompt` as the prompt and `stream` for all I/O. `prompt` -is optional and defaults to `node> `. `stream` is optional and defaults to +is optional and defaults to `> `. `stream` is optional and defaults to `process.openStdin()`. Multiple REPLs may be started against the same running instance of node. Each @@ -60,7 +60,7 @@ REPL clients may connect through the Unix socket or TCP socket. `telnet` is usef for connecting to TCP sockets, and `socat` can be used to connect to both Unix and TCP sockets. -By starting a REPL from a Unix socket-based server instead of stdin, you can +By starting a REPL from a Unix socket-based server instead of stdin, you can connect to a long-running node process without restarting it. @@ -70,14 +70,14 @@ Inside the REPL, Control+D will exit. Multi-line expressions can be input. The special variable `_` (underscore) contains the result of the last expression. - node> [ "a", "b", "c" ] + > [ "a", "b", "c" ] [ 'a', 'b', 'c' ] - node> _.length + > _.length 3 - node> _ += 1 + > _ += 1 4 -The REPL provides access to any variables in the global scope. You can expose a variable +The REPL provides access to any variables in the global scope. You can expose a variable to the REPL explicitly by assigning it to the `context` object associated with each `REPLServer`. For example: @@ -89,8 +89,8 @@ to the REPL explicitly by assigning it to the `context` object associated with e Things in the `context` object appear as local within the REPL: - mjr:~$ node repl_test.js - node> m + mjr:~$ node repl_test.js + > m 'message' There are a few special REPL commands: diff --git a/doc/api/url.markdown b/doc/api/url.markdown index d1e6123..5f9b31f 100644 --- a/doc/api/url.markdown +++ b/doc/api/url.markdown @@ -9,17 +9,17 @@ string will not be in the parsed object. Examples are shown for the URL `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'` -* `href`: The full URL that was originally parsed. - +* `href`: The full URL that was originally parsed. + Example: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'` * `protocol`: The request protocol. - + Example: `'http:'` -* `host`: The full host portion of the URL, including port and authentication information. - +* `host`: The full host portion of the URL, including port and authentication information. + Example: `'user:pass@host.com:8080'` * `auth`: The authentication information portion of a URL. - + Example: `'user:pass'` * `hostname`: Just the hostname portion of the host.