doc: two minor stream doc improvements

jasnell · jasnell · commit f7af915d52a8 · 2015-07-10T09:15:46.000-07:00
per: #14596 1. document that a runtime error will occur if you attempt to unshift after the end event 2. document that calling read after the end event will return null and will not trigger a runtime error Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635
diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown
@@ -228,7 +228,7 @@ returns it.  If there is no data available, then it will return
 
 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`,
-unless we've ended, in which case it will return the data remaining 
+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
@@ -251,6 +251,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.
@@ -422,6 +425,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.)
