doc updates from joyent/node

doc/api/child_process.markdown

@@ -88,7 +88,7 @@ and the `.connected` property is false.
 * `message` {Object} a parsed JSON object or primitive value
 * `sendHandle` {Handle object} a Socket or Server object
 
-Messages send by `.send(message, [sendHandle])` are obtained using the
+Messages sent by `.send(message, [sendHandle])` are obtained using the
 `message` event.
 
 ### child.stdin
@@ -315,7 +315,7 @@ process.
         special.send('socket', socket);
         return;
       }
-      // just the usual dudes
+      // just the usual...
       normal.send('socket', socket);
     });
     server.listen(1337);

doc/api/cluster.markdown

@@ -24,7 +24,7 @@ all share server ports.
       });
     } else {
       // Workers can share any TCP connection
-      // In this case its a HTTP server
+      // In this case it is an HTTP server
       http.createServer(function(req, res) {
         res.writeHead(200);
         res.end("hello world\n");
@@ -384,7 +384,7 @@ it can be obtained using `cluster.worker`.
 
 ### worker.id
 
-* {String}
+* {Number}
 
 Each new worker is given its own unique id, this id is stored in the
 `id`.

doc/api/crypto.markdown

@@ -135,7 +135,7 @@ Returned by `crypto.createHash`.
 
 Updates the hash content with the given `data`, the encoding of which
 is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
-`'binary'`.  If no encoding is provided and the input is a string an
+`'binary'`.  If no encoding is provided, and the input is a string, an
 encoding of `'binary'` is enforced. If `data` is a `Buffer` then
 `input_encoding` is ignored.
 
@@ -323,7 +323,7 @@ called.
 
 You can disable auto padding if the data has been encrypted without
 standard block padding to prevent `decipher.final` from checking and
-removing it. Can only work if the input data's length is a multiple of
+removing it. This will only work if the input data's length is a multiple of
 the ciphers block size. You must call this before streaming data to
 `decipher.update`.
 

doc/api/dgram.markdown

@@ -158,15 +158,16 @@ a packet might travel, and that generally sending a datagram greater than
 the (receiver) `MTU` won't work (the packet gets silently dropped, without
 informing the source that the data did not reach its intended recipient).
 
-### socket.bind(port[, address][, callback])
+### socket.bind([port][, address][, callback])
 
-* `port` Integer
+* `port` Integer, Optional
 * `address` String, Optional
 * `callback` Function with no parameters, Optional. Callback when
   binding is done.
 
 For UDP sockets, listen for datagrams on a named `port` and optional
-`address`. If `address` is not specified, the OS will try to listen on
+`address`. If `port` is not specified, the OS will try to bind to a random
+port. If `address` is not specified, the OS will try to listen on
 all addresses.  After binding is done, a "listening" event is emitted
 and the `callback`(if specified) is called. Specifying both a
 "listening" event listener and `callback` is not harmful but not very

doc/api/domain.markdown

@@ -32,7 +32,7 @@ process.  Of course, in a normal web server, you might have many
 connections open, and it is not reasonable to abruptly shut those down
 because an error was triggered by someone else.
 
-The better approach is send an error response to the request that
+The better approach is to send an error response to the request that
 triggered the error, while letting the others finish in their normal
 time, and stop listening for new requests in that worker.
 

doc/api/fs.markdown

@@ -8,7 +8,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.
 
-The asynchronous form always take a completion callback as its last argument.
+The asynchronous form always takes a completion callback as its last argument.
 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`.
@@ -59,8 +59,8 @@ In busy processes, the programmer is _strongly encouraged_ to use the
 asynchronous versions of these calls. The synchronous versions will block
 the entire process until they complete--halting all connections.
 
-Relative path to filename can be used, remember however that this path will be
-relative to `process.cwd()`.
+The relative path to a filename can be used. Remember, however, that this path
+will be relative to `process.cwd()`.
 
 Most fs functions let you omit the callback argument. If you do, a default
 callback is used that rethrows errors. To get a trace to the original call
@@ -574,7 +574,7 @@ stat object:
 
 These stat objects are instances of `fs.Stat`.
 
-If you want to be notified when the file was modified, not just accessed
+If you want to be notified when the file was modified, not just accessed,
 you need to compare `curr.mtime` and `prev.mtime`.
 
 _Note: when an `fs.watchFile` operation results in an `ENOENT` error, it will
@@ -680,15 +680,11 @@ Then call the `callback` argument with either true or false.  Example:
       console.log(exists ? "it's there" : 'no passwd!');
     });
 
-`fs.exists()` is an anachronism and exists only for historical reasons.
-There should almost never be a reason to use it in your own code.
-
-In particular, checking if a file exists before opening it is an anti-pattern
-that leaves you vulnerable to race conditions: another process may remove the
-file between the calls to `fs.exists()` and `fs.open()`.  Just open the file
-and handle the error when it's not there.
-
-
+`fs.exists()` should not be used to check if a file exists before calling
+`fs.open()`. Doing so introduces a race condition since other processes may
+change the file's state between the two calls. Instead, user code should
+call `fs.open()` directly and handle the error raised if the file is
+non-existent.
 
 ## fs.existsSync(path)
 

doc/api/globals.markdown

@@ -143,8 +143,6 @@ when to use `module.exports`.
 
 See the [module system documentation][] for more information.
 
-See the [module section][] for more information.
-
 ## setTimeout(cb, ms)
 
 Run callback `cb` after *at least* `ms` milliseconds. The actual delay depends
@@ -183,7 +181,6 @@ will not execute.
 The timer functions are global variables. See the [timers][] section.
 
 [buffer section]: buffer.html
-[module section]: modules.html
 [module system documentation]: modules.html
 [Modules]: modules.html#modules_modules
 [process object]: process.html#process_process

doc/api/modules.markdown

@@ -120,7 +120,12 @@ plan accordingly.
 Node.js has several modules compiled into the binary.  These modules are
 described in greater detail elsewhere in this documentation.
 
+<<<<<<< HEAD
 The core modules are defined in Node.js's source in the `lib/` folder.
+=======
+The core modules are defined within io.js's source and are located in the
+`lib/` folder.
+>>>>>>> doc: small clarifications to modules.markdown
 
 Core modules are always preferentially loaded if their identifier is
 passed to `require()`.  For instance, `require('http')` will always
@@ -130,23 +135,29 @@ return the built in HTTP module, even if there is a file by that name.
 
 <!--type=misc-->
 
+<<<<<<< HEAD
 If the exact filename is not found, then Node.js will attempt to load the
 required filename with the added extension of `.js`, `.json`, and then `.node`.
+=======
+If the exact filename is not found, then io.js will attempt to load the
+required filename with the added extensions: `.js`, `.json`, and finally
+`.node`.
+>>>>>>> doc: small clarifications to modules.markdown
 
 `.js` files are interpreted as JavaScript text files, and `.json` files are
 parsed as JSON text files. `.node` files are interpreted as compiled addon
 modules loaded with `dlopen`.
 
-A module prefixed with `'/'` is an absolute path to the file.  For
+A required module prefixed with `'/'` is an absolute path to the file.  For
 example, `require('/home/marco/foo.js')` will load the file at
 `/home/marco/foo.js`.
 
-A module prefixed with `'./'` is relative to the file calling `require()`.
-That is, `circle.js` must be in the same directory as `foo.js` for
+A required module prefixed with `'./'` is relative to the file calling
+`require()`. That is, `circle.js` must be in the same directory as `foo.js` for
 `require('./circle')` to find it.
 
-Without a leading '/', './', or '../' to indicate a file, the module is either a
-core module or is loaded from a `node_modules` folder.
+Without a leading '/', './', or '../' to indicate a file, the module must
+either be a core module or is loaded from a `node_modules` folder.
 
 If the given path does not exist, `require()` will throw an Error with its
 `code` property set to `'MODULE_NOT_FOUND'`.
@@ -357,8 +368,7 @@ loading.
 
 * {Module Object}
 
-The module that required this one.
-
+The module that first required this one.
 
 ### module.children
 

doc/api/net.markdown

@@ -57,8 +57,8 @@ Use `nc` to connect to a UNIX domain socket server:
 
     nc -U /tmp/echo.sock
 
-## net.connect(options[, connectionListener])
-## net.createConnection(options[, connectionListener])
+## net.connect(options[, connectListener])
+## net.createConnection(options[, connectListener])
 
 A factory function, which returns a new ['net.Socket'](#net_class_net_socket)
 and automatically connects with the supplied `options`.
@@ -334,7 +334,7 @@ Construct a new socket object.
 
 `options` is an object with the following defaults:
 
-    { fd: null
+    { fd: null,
       allowHalfOpen: false,
       readable: false,
       writable: false

doc/api/path.markdown

@@ -183,6 +183,10 @@ an empty string.  Examples:
     // returns
     ''
 
+    path.extname('.index')
+    // returns
+    ''
+
 ## path.sep
 
 The platform-specific file separator. `'\\'` or `'/'`.

doc/api/repl.markdown

@@ -117,32 +117,31 @@ will share the same global object but will have unique I/O.
 
 Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:
 
-    var net = require("net"),
-        repl = require("repl");
-
-    connections = 0;
+    var net = require('net'),
+        repl = require('repl'),
+        connections = 0;
 
     repl.start({
-      prompt: "Node.js via stdin> ",
+      prompt: 'Node.js via stdin> ',
       input: process.stdin,
       output: process.stdout
     });
 
     net.createServer(function (socket) {
       connections += 1;
       repl.start({
-        prompt: "Node.js via Unix socket> ",
+        prompt: 'Node.js via Unix socket> ',
         input: socket,
         output: socket
       }).on('exit', function() {
         socket.end();
       })
-    }).listen("/tmp/node-repl-sock");
+    }).listen('/tmp/node-repl-sock');
 
     net.createServer(function (socket) {
       connections += 1;
       repl.start({
-        prompt: "Node.js via TCP socket> ",
+        prompt: 'Node.js via TCP socket> ',
         input: socket,
         output: socket
       }).on('exit', function() {
@@ -191,7 +190,7 @@ be emitted.
 Example of listening for `reset`:
 
     // Extend the initial repl context.
-    r = repl.start({ options ... });
+    var r = repl.start({ options ... });
     someExtension.extend(r.context);
 
     // When a new context is created extend it as well.
@@ -213,7 +212,7 @@ accessing `fs` will `require()` the `fs` module as `global.fs`.
 
 The special variable `_` (underscore) contains the result of the last expression.
 
-    > [ "a", "b", "c" ]
+    > [ 'a', 'b', 'c' ]
     [ 'a', 'b', 'c' ]
     > _.length
     3
@@ -225,10 +224,10 @@ a variable to the REPL explicitly by assigning it to the `context` object
 associated with each `REPLServer`.  For example:
 
     // repl_test.js
-    var repl = require("repl"),
-        msg = "message";
+    var repl = require('repl'),
+        msg = 'message';
 
-    repl.start("> ").context.m = msg;
+    repl.start('> ').context.m = msg;
 
 Things in the `context` object appear as local within the REPL:
 

doc/api/stream.markdown

@@ -230,8 +230,11 @@ readable.on('end', function() {
 
 #### Event: 'close'
 
-Emitted when the underlying resource (for example, the backing file
-descriptor) has been closed. Not all streams will emit this.
+Emitted when the stream and any of its underlying resources (a file
+descriptor, for example) have been closed. The event indicates that
+no more events will be emitted, and no further computation will occur.
+
+Not all streams will emit the 'close' event.
 
 #### Event: 'error'
 
@@ -1215,19 +1218,19 @@ as a result of this chunk.
 
 Call the callback function only when the current chunk is completely
 consumed.  Note that there may or may not be output as a result of any
-particular input chunk. If you supply output as the second argument to the
-callback, it will be passed to push method, in other words the following are
+particular input chunk. If you supply a second argument to the callback
+it will be passed to the push method. In other words the following are
 equivalent:
 
 ```javascript
 transform.prototype._transform = function (data, encoding, callback) {
   this.push(data);
   callback();
-}
+};
 
 transform.prototype._transform = function (data, encoding, callback) {
   callback(null, data);
-}
+};
 ```
 
 This method is prefixed with an underscore because it is internal to