From 4cf0ce5bb4c20ed7e145785988d9be56671a0c69 Mon Sep 17 00:00:00 2001 From: Thomas Shinnick Date: Wed, 31 Aug 2011 08:12:34 -0500 Subject: [PATCH] docs: typos and minor edits in several modules 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. --- doc/api/events.markdown | 8 ++++---- doc/api/fs.markdown | 19 ++++++++++-------- doc/api/globals.markdown | 10 ++++++---- doc/api/http.markdown | 4 ++-- doc/api/net.markdown | 42 +++++++++++++++++++++++++++------------- doc/api/path.markdown | 32 ++++++++++++++++++++---------- doc/api/stdio.markdown | 4 +++- doc/api/streams.markdown | 4 +++- doc/api/timers.markdown | 6 +++--- 9 files changed, 83 insertions(+), 46 deletions(-) diff --git a/doc/api/events.markdown b/doc/api/events.markdown index cf1ec9216b..660f36e178 100644 --- 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 index 6cc7f78178..e2722df77d 100644 --- 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 index 6ac5f2c328..cc457a7c42 100644 --- 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 index 05930beb63..bc7bbb3f93 100644 --- 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 index fb1a4be8ae..a6e9f8fb14 100644 --- 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 index 2c34eaac4a..ba48bd29c8 100644 --- 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 index 836be833e0..e14e8b920b 100644 --- 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 index 01a841a1c3..39cd21c0cf 100644 --- 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 index 2ac0236994..de3f6d027b 100644 --- a/doc/api/timers.markdown +++ b/doc/api/timers.markdown @@ -2,8 +2,8 @@ ### setTimeout(callback, delay, [arg], [...]) -To schedule execution of `callback` after `delay` milliseconds. Returns a -`timeoutId` for possible use with `clearTimeout()`. Optionally, you can +To schedule execution of a one-time `callback` after `delay` milliseconds. Returns a +`timeoutId` for possible use with `clearTimeout()`. Optionally you can also pass arguments to the callback. ### clearTimeout(timeoutId) @@ -13,7 +13,7 @@ Prevents a timeout from triggering. ### setInterval(callback, delay, [arg], [...]) To schedule the repeated execution of `callback` every `delay` milliseconds. -Returns a `intervalId` for possible use with `clearInterval()`. Optionally, +Returns a `intervalId` for possible use with `clearInterval()`. Optionally you can also pass arguments to the callback. ### clearInterval(intervalId)