doc: a handful of doc improvements

doc/api/buffer.markdown

@@ -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/fs.markdown

@@ -797,6 +797,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 +823,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

@@ -910,7 +910,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/stream.markdown

@@ -164,6 +164,9 @@ 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.
+
 #### Event: 'data'
 
 * `chunk` {Buffer | String} The chunk of data.
@@ -181,6 +184,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'
 

doc/api/tls.markdown

@@ -766,6 +766,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.39 and prior has been
+deprecated and removed.
+
 ## Class: tls.TLSSocket
 
 This is a wrapped version of [net.Socket][] that does transparent encryption