doc: Formatting and grammar on stream api doc

doc/api/stream.markdown

@@ -2,9 +2,10 @@
 
     Stability: 2 - Unstable
 
-A stream is an abstract interface implemented by various objects in Node.
+A stream is an abstract interface implemented by various objects in
-For example a request to an HTTP server is a stream, as is stdout. Streams
+Node.  For example a request to an HTTP server is a stream, as is
-are readable, writable, or both. All streams are instances of [EventEmitter][]
+stdout. Streams are readable, writable, or both. All streams are
+instances of [EventEmitter][]
 
 You can load up the Stream base class by doing `require('stream')`.
 
@@ -29,8 +30,8 @@ Note that the __data will be lost__ if there is no listener when a
 `function () { }`
 
 Emitted when the stream has received an EOF (FIN in TCP terminology).
-Indicates that no more `'data'` events will happen. If the stream is also
+Indicates that no more `'data'` events will happen. If the stream is
-writable, it may be possible to continue writing.
+also writable, it may be possible to continue writing.
 
 ### Event: 'error'
 
@@ -42,28 +43,30 @@ Emitted if there was an error receiving data.
 
 `function () { }`
 
-Emitted when the underlying resource (for example, the backing file descriptor)
+Emitted when the underlying resource (for example, the backing file
-has been closed. Not all streams will emit this.
+descriptor) has been closed. Not all streams will emit this.
 
 ### stream.readable
 
-A boolean that is `true` by default, but turns `false` after an `'error'`
+A boolean that is `true` by default, but turns `false` after an
-occurred, the stream came to an `'end'`, or `destroy()` was called.
+`'error'` occurred, the stream came to an `'end'`, or `destroy()` was
+called.
 
 ### stream.setEncoding([encoding])
 
-Makes the `'data'` event emit a string instead of a `Buffer`. `encoding` can be
+Makes the `'data'` event emit a string instead of a `Buffer`. `encoding`
-`'utf8'`, `'utf16le'` (`'ucs2'`), `'ascii'`, or `'hex'`. Defaults to `'utf8'`.
+can be `'utf8'`, `'utf16le'` (`'ucs2'`), `'ascii'`, or `'hex'`. Defaults
+to `'utf8'`.
 
 ### stream.pause()
 
-Issues an advisory signal to the underlying communication layer, requesting
+Issues an advisory signal to the underlying communication layer,
-that no further data be sent until `resume()` is called.
+requesting that no further data be sent until `resume()` is called.
 
-Note that, due to the advisory nature, certain streams will not be paused
+Note that, due to the advisory nature, certain streams will not be
-immediately, and so `'data'` events may be emitted for some indeterminate
+paused immediately, and so `'data'` events may be emitted for some
-period of time even after `pause()` is called. You may wish to buffer such
+indeterminate period of time even after `pause()` is called. You may
-`'data'` events.
+wish to buffer such `'data'` events.
 
 ### stream.resume()
 
@@ -71,37 +74,40 @@ Resumes the incoming `'data'` events after a `pause()`.
 
 ### stream.destroy()
 
-Closes the underlying file descriptor. Stream will not emit any more events.
+Closes the underlying file descriptor. Stream is no longer `writable`
+nor `readable`.  The stream will not emit any more 'data', or 'end'
+events. Any queued write data will not be sent.  The stream should emit
+'close' event once its resources have been disposed of.
+
 
 ### stream.pipe(destination, [options])
 
 This is a `Stream.prototype` method available on all `Stream`s.
 
-Connects this read stream to `destination` WriteStream. Incoming
+Connects this read stream to `destination` WriteStream. Incoming data on
-data on this stream gets written to `destination`. The destination and source
+this stream gets written to `destination`. The destination and source
 streams are kept in sync by pausing and resuming as necessary.
 
 This function returns the `destination` stream.
 
 Emulating the Unix `cat` command:
 
-    process.stdin.resume();
+    process.stdin.resume(); process.stdin.pipe(process.stdout);
-    process.stdin.pipe(process.stdout);
 
 
-By default `end()` is called on the destination when the source stream emits
+By default `end()` is called on the destination when the source stream
-`end`, so that `destination` is no longer writable. Pass `{ end: false }` as
+emits `end`, so that `destination` is no longer writable. Pass `{ end:
-`options` to keep the destination stream open.
+false }` as `options` to keep the destination stream open.
 
-This keeps `process.stdout` open so that "Goodbye" can be written at the end.
+This keeps `process.stdout` open so that "Goodbye" can be written at the
+end.
 
     process.stdin.resume();
 
     process.stdin.pipe(process.stdout, { end: false });
 
     process.stdin.on("end", function() {
-      process.stdout.write("Goodbye\n");
+    process.stdout.write("Goodbye\n"); });
-    });
 
 
 ## Writable Stream
@@ -137,22 +143,22 @@ Emitted when the stream is passed to a readable stream's pipe method.
 
 ### stream.writable
 
-A boolean that is `true` by default, but turns `false` after an `'error'`
+A boolean that is `true` by default, but turns `false` after an
-occurred or `end()` / `destroy()` was called.
+`'error'` occurred or `end()` / `destroy()` was called.
 
 ### stream.write(string, [encoding], [fd])
 
-Writes `string` with the given `encoding` to the stream.  Returns `true` if
+Writes `string` with the given `encoding` to the stream.  Returns `true`
-the string has been flushed to the kernel buffer.  Returns `false` to
+if the string has been flushed to the kernel buffer.  Returns `false` to
-indicate that the kernel buffer is full, and the data will be sent out in
+indicate that the kernel buffer is full, and the data will be sent out
-the future. The `'drain'` event will indicate when the kernel buffer is
+in the future. The `'drain'` event will indicate when the kernel buffer
-empty again. The `encoding` defaults to `'utf8'`.
+is empty again. The `encoding` defaults to `'utf8'`.
 
-If the optional `fd` parameter is specified, it is interpreted as an integral
+If the optional `fd` parameter is specified, it is interpreted as an
-file descriptor to be sent over the stream. This is only supported for UNIX
+integral file descriptor to be sent over the stream. This is only
-streams, and is silently ignored otherwise. When writing a file descriptor in
+supported for UNIX streams, and is silently ignored otherwise. When
-this manner, closing the descriptor before the stream drains risks sending an
+writing a file descriptor in this manner, closing the descriptor before
-invalid (closed) FD.
+the stream drains risks sending an invalid (closed) FD.
 
 ### stream.write(buffer)
 
@@ -160,13 +166,13 @@ Same as the above except with a raw buffer.
 
 ### stream.end()
 
-Terminates the stream with EOF or FIN.
+Terminates the stream with EOF or FIN.  This call will allow queued
-This call will allow queued write data to be sent before closing the stream.
+write data to be sent before closing the stream.
 
 ### stream.end(string, encoding)
 
-Sends `string` with the given `encoding` and terminates the stream with EOF
+Sends `string` with the given `encoding` and terminates the stream with
-or FIN. This is useful to reduce the number of packets sent.
+EOF or FIN. This is useful to reduce the number of packets sent.
 
 ### stream.end(buffer)
 
@@ -174,14 +180,15 @@ Same as above but with a `buffer`.
 
 ### stream.destroy()
 
-Closes the underlying file descriptor. Stream is no longer `writable` nor `readable`.
+Closes the underlying file descriptor. Stream is no longer `writable`
-the stream will not emit any more 'data', or 'end' events. Any queued write data will not be sent.
+nor `readable`.  The stream will not emit any more 'data', or 'end'
-the stream should emit 'close' event once it's resources have been disposed of.
+events. Any queued write data will not be sent.  The stream should emit
+'close' event once its resources have been disposed of.
 
 ### stream.destroySoon()
 
-After the write queue is drained, close the file descriptor. `destroySoon()`
+After the write queue is drained, close the file descriptor.
-can still destroy straight away, as long as there is no data left in the queue
+`destroySoon()` can still destroy straight away, as long as there is no
-for writes.
+data left in the queue for writes.
 
 [EventEmitter]: events.html#events_class_events_eventemitter