doc: clarify Readable._read and Readable.push

Minor clarifications around Readable._read and Readable.push
to make their implementation/usage easier to understand.

https://github.com/joyent/node/issues/14124#issuecomment-115392674

Reviewed-By: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/joyent/node/pull/25635

1 files changed, 20 insertions, 25 deletions

diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown
index dfc9a6d32..71a8e4ebb 100644
--- a/doc/api/stream.markdown
+++ b/doc/api/stream.markdown
@@ -944,24 +944,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.
+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.
 
-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 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
@@ -977,19 +975,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