doc: apply multiple doc updates from master to v0.12

doc/api/buffer.markdown

@@ -43,7 +43,7 @@ Creating a typed array from a `Buffer` works with the following caveats:
 
 2. The buffer's memory is interpreted as an array, not a byte array.  That is,
    `new Uint32Array(new Buffer([1,2,3,4]))` creates a 4-element `Uint32Array`
-   with elements `[1,2,3,4]`, not an `Uint32Array` with a single element
+   with elements `[1,2,3,4]`, not a `Uint32Array` with a single element
    `[0x1020304]` or `[0x4030201]`.
 
 NOTE: Node.js v0.8 simply retained a reference to the buffer in `array.buffer`
@@ -64,7 +64,9 @@ It can be constructed in a variety of ways.
 
 Allocates a new buffer of `size` octets. Note, `size` must be no more than
 [kMaxLength](smalloc.html#smalloc_smalloc_kmaxlength). Otherwise, a `RangeError`
-will be thrown here.
+will be thrown here. Unlike `ArrayBuffers`, the underlying memory for buffers
+is not initialized. So the contents of a newly created `Buffer` is unknown.
+Use `buf.fill(0)`to initialize a buffer to zeroes.
 
 ### new Buffer(array)
 

doc/api/child_process.markdown

@@ -274,7 +274,7 @@ Here is an example of sending a server:
       child.send('server', server);
     });
 
-And the child would the receive the server object as:
+And the child would then receive the server object as:
 
     process.on('message', function(m, server) {
       if (m === 'server') {

doc/api/cluster.markdown

@@ -599,7 +599,7 @@ It is not emitted in the worker.
 
 ### Event: 'disconnect'
 
-Similar to the `cluster.on('disconnect')` event, but specfic to this worker.
+Similar to the `cluster.on('disconnect')` event, but specific to this worker.
 
     cluster.fork().on('disconnect', function() {
       // Worker has disconnected

doc/api/crypto.markdown

@@ -529,7 +529,7 @@ Example (obtaining a shared secret):
 
 ## crypto.createECDH(curve_name)
 
-Creates a Elliptic Curve (EC) Diffie-Hellman key exchange object using a
+Creates an Elliptic Curve (EC) Diffie-Hellman key exchange object using a
 predefined curve specified by `curve_name` string.
 
 ## Class: ECDH

doc/api/dns.markdown

@@ -81,7 +81,7 @@ See [supported `getaddrinfo` flags](#dns_supported_getaddrinfo_flags) below for
 more information on supported flags.
 
 The callback has arguments `(err, address, family)`.  The `address` argument
-is a string representation of a IP v4 or v6 address. The `family` argument
+is a string representation of an IP v4 or v6 address. The `family` argument
 is either the integer 4 or 6 and denotes the family of `address` (not
 necessarily the value initially passed to `lookup`).
 
@@ -155,7 +155,7 @@ attribute (e.g. `[{'priority': 10, 'exchange': 'mx.example.com'},...]`).
 ## dns.resolveTxt(hostname, callback)
 
 The same as `dns.resolve()`, but only for text queries (`TXT` records).
-`addresses` is an 2-d array of the text records available for `hostname` (e.g.,
+`addresses` is a 2-d array of the text records available for `hostname` (e.g.,
 `[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of
 one record. Depending on the use case, the could be either joined together or
 treated separately.

doc/api/events.markdown

@@ -104,7 +104,7 @@ Note that `emitter.setMaxListeners(n)` still has precedence over
 
 ### emitter.listeners(event)
 
-Returns an array of listeners for the specified event.
+Returns a copy of the array of listeners for the specified event.
 
     server.on('connection', function (stream) {
       console.log('someone connected!');

doc/api/fs.markdown

@@ -775,6 +775,10 @@ on Unix systems, it never was.
 
 Returns a new ReadStream object (See `Readable Stream`).
 
+Be aware that, unlike the default value set for `highWaterMark` on a
+readable stream (16kB), the stream returned by this method has a
+default value of 64kB for the same parameter.
+
 `options` is an object with the following defaults:
 
     { flags: 'r',
@@ -797,6 +801,9 @@ there's no file descriptor leak.  If `autoClose` is set to true (default
 behavior), on `error` or `end` the file descriptor will be closed
 automatically.
 
+`mode` sets the file mode (permission and sticky bits), but only if the
+file was created.
+
 An example to read the last 10 bytes of a file which is 100 bytes long:
 
     fs.createReadStream('sample.txt', {start: 90, end: 99});
@@ -820,7 +827,7 @@ Returns a new WriteStream object (See `Writable Stream`).
 `options` is an object with the following defaults:
 
     { flags: 'w',
-      encoding: null,
+      defaultEncoding: 'utf8',
       fd: null,
       mode: 0666 }
 

doc/api/http.markdown

@@ -457,6 +457,7 @@ automatically parsed with [url.parse()][].
 
 Options:
 
+- `protocol`: Protocol to use. Defaults to `'http:'`.
 - `host`: A domain name or IP address of the server to issue the request to.
   Defaults to `'localhost'`.
 - `hostname`: To support `url.parse()` `hostname` is preferred over `host`
@@ -897,7 +898,8 @@ is finished.
 
 ### request.abort()
 
-Aborts a request.  (New since v0.3.8.)
+Marks the request as aborting. Calling this will cause remaining data
+in the response to be dropped and the socket to be destroyed.
 
 ### request.setTimeout(timeout[, callback])
 

doc/api/net.markdown

@@ -90,7 +90,7 @@ Common options are:
     a FIN packet when the other end of the socket sends a FIN packet.
     Defaults to `false`.  See ['end'][] event for more information.
 
-The `connectListener` parameter will be added as an listener for the
+The `connectListener` parameter will be added as a listener for the
 ['connect'][] event.
 
 Here is an example of a client of echo server as described previously:
@@ -119,7 +119,7 @@ changed to
 
 Creates a TCP connection to `port` on `host`. If `host` is omitted,
 `'localhost'` will be assumed.
-The `connectListener` parameter will be added as an listener for the
+The `connectListener` parameter will be added as a listener for the
 ['connect'][] event.
 
 Is a factory method which returns a new ['net.Socket'](#net_class_net_socket).
@@ -128,7 +128,7 @@ Is a factory method which returns a new ['net.Socket'](#net_class_net_socket).
 ## net.createConnection(path[, connectListener])
 
 Creates unix socket connection to `path`.
-The `connectListener` parameter will be added as an listener for the
+The `connectListener` parameter will be added as a listener for the
 ['connect'][] event.
 
 A factory method which returns a new ['net.Socket'](#net_class_net_socket).
@@ -150,7 +150,7 @@ parameter is 511 (not 512).
 
 This function is asynchronous.  When the server has been bound,
 ['listening'][] event will be emitted.  The last parameter `callback`
-will be added as an listener for the ['listening'][] event.
+will be added as a listener for the ['listening'][] event.
 
 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
@@ -178,7 +178,7 @@ Start a local socket server listening for connections on the given `path`.
 
 This function is asynchronous.  When the server has been bound,
 ['listening'][] event will be emitted.  The last parameter `callback`
-will be added as an listener for the ['listening'][] event.
+will be added as a listener for the ['listening'][] event.
 
 On UNIX, the local domain is usually known as the UNIX domain. The path is a
 filesystem path name. It is subject to the same naming conventions and
@@ -212,7 +212,7 @@ Listening on a file descriptor is not supported on Windows.
 
 This function is asynchronous.  When the server has been bound,
 ['listening'][] event will be emitted.
-the last parameter `callback` will be added as an listener for the
+the last parameter `callback` will be added as a listener for the
 ['listening'][] event.
 
 ### server.listen(options[, callback])
@@ -374,7 +374,7 @@ This function is asynchronous. When the ['connect'][] event is emitted the
 socket is established. If there is a problem connecting, the `'connect'` event
 will not be emitted, the `'error'` event will be emitted with the exception.
 
-The `connectListener` parameter will be added as an listener for the
+The `connectListener` parameter will be added as a listener for the
 ['connect'][] event.
 
 

doc/api/stream.markdown

@@ -164,6 +164,34 @@ readable.on('readable', function() {
 Once the internal buffer is drained, a `readable` event will fire
 again when more data is available.
 
+The `readable` event is not emitted in the "flowing" mode with the
+sole exception of the last one, on end-of-stream.
+
+The 'readable' event indicates that the stream has new information:
+either new data is available or the end of the stream has been reached.
+In the former case, `.read()` will return that data. In the latter case,
+`.read()` will return null. For instance, in the following example, `foo.txt`
+is an empty file:
+
+```javascript
+var fs = require('fs');
+var rr = fs.createReadStream('foo.txt');
+rr.on('readable', function() {
+  console.log('readable:', rr.read());
+});
+rr.on('end', function() {
+  console.log('end');
+});
+```
+
+The output of running this script is:
+
+```
+bash-3.2$ node test.js
+readable: null
+end
+```
+
 #### Event: 'data'
 
 * `chunk` {Buffer | String} The chunk of data.
@@ -181,6 +209,9 @@ readable.on('data', function(chunk) {
   console.log('got %d bytes of data', chunk.length);
 });
 ```
+Note that the `readable` event should not be used together with `data`
+because the assigning the latter switches the stream into "flowing" mode,
+so the `readable` event will not be emitted.
 
 #### Event: 'end'
 
@@ -221,7 +252,9 @@ returns it.  If there is no data available, then it will return
 `null`.
 
 If you pass in a `size` argument, then it will return that many
-bytes.  If `size` bytes are not available, then it will return `null`.
+bytes.  If `size` bytes are not available, then it will return `null`,
+unless we've ended, in which case it will return the data remaining
+in the buffer.
 
 If you do not specify a `size` argument, then it will return all the
 data in the internal buffer.
@@ -243,6 +276,9 @@ readable.on('readable', function() {
 If this method returns a data chunk, then it will also trigger the
 emission of a [`'data'` event][].
 
+Note that calling `readable.read([size])` after the `end` event has been
+triggered will return `null`. No runtime error will be raised.
+
 #### readable.setEncoding(encoding)
 
 * `encoding` {String} The encoding to use.
@@ -414,6 +450,9 @@ parser, which needs to "un-consume" some data that it has
 optimistically pulled out of the source, so that the stream can be
 passed on to some other party.
 
+Note that `stream.unshift(chunk)` cannot be called after the `end` event
+has been triggered; a runtime error will be raised.
+
 If you find that you must often call `stream.unshift(chunk)` in your
 programs, consider implementing a [Transform][] stream instead.  (See API
 for Stream Implementors, below.)
@@ -452,6 +491,13 @@ function parseHeader(stream, callback) {
   }
 }
 ```
+Note that, unlike `stream.push(chunk)`, `stream.unshift(chunk)` will not
+end the reading process by resetting the internal reading state of the
+stream. This can cause unexpected results if `unshift` is called during a
+read (i.e. from within a `_read` implementation on a custom stream). Following
+the call to `unshift` with an immediate `stream.push('')` will reset the
+reading state appropriately, however it is best to simply avoid calling
+`unshift` while in the process of performing a read.
 
 #### readable.wrap(stream)
 
@@ -891,6 +937,10 @@ SimpleProtocol.prototype._read = function(n) {
       // back into the read queue so that our consumer will see it.
       var b = chunk.slice(split);
       this.unshift(b);
+      // calling unshift by itself does not reset the reading state
+      // of the stream; since we're inside _read, doing an additional
+      // push('') will reset the state appropriately.
+      this.push('');
 
       // and let them know that we are done parsing the header.
       this.emit('header', this.header);
@@ -930,24 +980,22 @@ initialized.
 
 * `size` {Number} Number of bytes to read asynchronously
 
-Note: **Implement this function, but do NOT call it directly.**
+Note: **Implement this method, but do NOT call it directly.**
 
-This function should NOT be called directly.  It should be implemented
-by child classes, and only called by the internal Readable class
-methods.
+This method is prefixed with an underscore because it is internal to the
+class that defines it and should only be called by the internal Readable
+class methods. All Readable stream implementations must provide a _read
+method to fetch data from the underlying resource.
 
-All Readable stream implementations must provide a `_read` method to
-fetch data from the underlying resource.
-
-This method is prefixed with an underscore because it is internal to
-the class that defines it, and should not be called directly by user
-programs.  However, you **are** expected to override this method in
-your own extension classes.
+When _read is called, if data is available from the resource, `_read` should
+start pushing that data into the read queue by calling `this.push(dataChunk)`.
+`_read` should continue reading from the resource and pushing data until push
+returns false, at which point it should stop reading from the resource. Only
+when _read is called again after it has stopped should it start reading
+more data from the resource and pushing that data onto the queue.
 
-When data is available, put it into the read queue by calling
-`readable.push(chunk)`.  If `push` returns false, then you should stop
-reading.  When `_read` is called again, you should start pushing more
-data.
+Note: once the `_read()` method is called, it will not be called again until
+the `push` method is called.
 
 The `size` argument is advisory.  Implementations where a "read" is a
 single call that returns data can use this to know how much data to
@@ -963,19 +1011,16 @@ becomes available.  There is no need, for example to "wait" until
   Buffer encoding, such as `'utf8'` or `'ascii'`
 * return {Boolean} Whether or not more pushes should be performed
 
-Note: **This function should be called by Readable implementors, NOT
+Note: **This method should be called by Readable implementors, NOT
 by consumers of Readable streams.**
 
-The `_read()` function will not be called again until at least one
-`push(chunk)` call is made.
-
-The `Readable` class works by putting data into a read queue to be
-pulled out later by calling the `read()` method when the `'readable'`
-event fires.
+If a value other than null is passed, The `push()` method adds a chunk of data
+into the queue for subsequent stream processors to consume. If `null` is
+passed, it signals the end of the stream (EOF), after which no more data
+can be written.
 
-The `push()` method will explicitly insert some data into the read
-queue.  If it is called with `null` then it will signal the end of the
-data (EOF).
+The data added with `push` can be pulled out by calling the `read()` method
+when the `'readable'`event fires.
 
 This API is designed to be as flexible as possible.  For example,
 you may be wrapping a lower-level source which has some sort of

doc/api/tls.markdown

@@ -694,6 +694,11 @@ This is an encrypted stream.
 A proxy to the underlying socket's bytesWritten accessor, this will return
 the total bytes written to the socket, *including the TLS overhead*.
 
+## Class: CleartextStream
+
+The CleartextStream class in Node.js version v0.10.x (and prior) has been
+deprecated and removed.
+
 ## Class: tls.TLSSocket
 
 This is a wrapped version of [net.Socket][] that does transparent encryption

doc/api/util.markdown

@@ -261,7 +261,7 @@ through the `constructor.super_` property.
 
 Marks that a method should not be used any more.
 
-    exports.puts = exports.deprecate(function() {
+    exports.puts = util.deprecate(function() {
       for (var i = 0, len = arguments.length; i < len; ++i) {
         process.stdout.write(arguments[i] + '\n');
       }

lib/_http_client.js

@@ -371,7 +371,7 @@ function parserOnIncomingClient(res, shouldKeepAlive) {
   var req = socket._httpMessage;
 
 
-  // propogate "domain" setting...
+  // propagate "domain" setting...
   if (req.domain && !res.domain) {
     debug('setting "res.domain"');
     res.domain = req.domain;
@@ -474,7 +474,7 @@ function tickOnSocket(req, socket) {
   socket.parser = parser;
   socket._httpMessage = req;
 
-  // Setup "drain" propogation.
+  // Setup "drain" propagation.
   httpSocketSetup(socket);
 
   // Propagate headers limit from request object to parser