doc: several documentation improvements #25635

jasnell · 2015-07-06T18:39:15Z

bundled together to make landing them easier.

Clarifies that emitter.listener() returns a copy, not a reference Resolves issue nodejs#9022

per: nodejs#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

Minor clarifications around Readable._read and Readable.push to make their implementation/usage easier to understand. nodejs#14124 (comment)

Fix for nodejs#25559 (Typo in example of util.deprecate() documentation)

Per nodejs#14604, Document that performing an `unshift` during a read can have unexpected results. Following the `unshift` with a `push('')` resets the reading state appropriately. Also indicate that doing an `unshift` during a read is not optimal and should be avoided.

jasnell · 2015-07-06T18:39:26Z

@joyent/node-collaborators

trevnorris · 2015-07-06T18:44:42Z

doc/api/stream.markdown

+var fs = require('fs');
+var rr = fs.createReadStream('foo.txt');
+rr.on('readable', function() {
+  var chunk;


Is this variable only for demonstration? Not being used.

Ah...right, just mentally zoned on that one ;-). I'll remove the variable really quick

trevnorris · 2015-07-06T18:46:01Z

One question. Otherwise LGTM

per nodejs#14597 Indicate that `'readable'` indicates only that data can be read from the stream, not that there is actually data to be consumed. `readable.read([size])` can still return null. Includes an example that illustrates the point.

chrisdickinson · 2015-07-06T19:40:55Z

doc/api/stream.markdown

@@ -167,6 +167,32 @@ 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.

+Note that the `'readable'` event indicates only that data *can* be
+read from the stream. It does not indicate whether there is actual
+data to be consumed. The callback passed to handle the `'readable'`


The first two sentences are pretty confusing. Maybe:

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, ...

👍 will make that change

@chrisdickinson ... done... if it looks good to you I'll get it landed

Per nodejs#25635 (comment) Additional refinement to the clarification on the `readable` event

Clarifies that emitter.listener() returns a copy, not a reference Resolves issue #9022 Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

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

Minor clarifications around Readable._read and Readable.push to make their implementation/usage easier to understand. #14124 (comment) Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

Fix for #25559 (Typo in example of util.deprecate() documentation) Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

Per #14604, Document that performing an `unshift` during a read can have unexpected results. Following the `unshift` with a `push('')` resets the reading state appropriately. Also indicate that doing an `unshift` during a read is not optimal and should be avoided. Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

per #14597 Indicate that `'readable'` indicates only that data can be read from the stream, not that there is actually data to be consumed. `readable.read([size])` can still return null. Includes an example that illustrates the point. Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

Per #25635 (comment) Additional refinement to the clarification on the `readable` event Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

jasnell · 2015-07-10T17:31:47Z

Landed in f91fa52, f7af915, 9faae7a, 423c433, daed421, 340e9f0 and 6036e4f

Clarifies that emitter.listener() returns a copy, not a reference Resolves issue nodejs#9022 Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs#25635

per: nodejs#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: nodejs#25635

Minor clarifications around Readable._read and Readable.push to make their implementation/usage easier to understand. nodejs#14124 (comment) Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs#25635

Fix for nodejs#25559 (Typo in example of util.deprecate() documentation) Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs#25635

Per nodejs#14604, Document that performing an `unshift` during a read can have unexpected results. Following the `unshift` with a `push('')` resets the reading state appropriately. Also indicate that doing an `unshift` during a read is not optimal and should be avoided. Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs#25635

per nodejs#14597 Indicate that `'readable'` indicates only that data can be read from the stream, not that there is actually data to be consumed. `readable.read([size])` can still return null. Includes an example that illustrates the point. Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs#25635

Per nodejs#25635 (comment) Additional refinement to the clarification on the `readable` event Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs#25635

Per #25635 (comment) Additional refinement to the clarification on the `readable` event Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25591

Per nodejs/node-v0.x-archive#25635 (comment) Additional refinement to the clarification on the `readable` event Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs/node-v0.x-archive#25591

Per nodejs#25635 (comment) Additional refinement to the clarification on the `readable` event Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs#25591

bsteephenson and others added 5 commits June 29, 2015 12:13

docs:events clarify emitter.listener() behavior

b5c2933

Clarifies that emitter.listener() returns a copy, not a reference Resolves issue nodejs#9022

doc: two minor stream doc improvements

ec67d78

per: nodejs#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

doc: clarify Readable._read and Readable.push

003c1b2

Minor clarifications around Readable._read and Readable.push to make their implementation/usage easier to understand. nodejs#14124 (comment)

Update util.markdown

6528aed

Fix for nodejs#25559 (Typo in example of util.deprecate() documentation)

orangemocha added the in progress label Jul 6, 2015

trevnorris reviewed Jul 6, 2015
View reviewed changes

doc: readable event clarification

970e2f1

per nodejs#14597 Indicate that `'readable'` indicates only that data can be read from the stream, not that there is actually data to be consumed. `readable.read([size])` can still return null. Includes an example that illustrates the point.

jasnell force-pushed the doc-improvements3 branch from 1b9d4f3 to 970e2f1 Compare July 6, 2015 18:50

chrisdickinson reviewed Jul 6, 2015
View reviewed changes

doc: additional refinement to readable event

4ed55ff

Per nodejs#25635 (comment) Additional refinement to the clarification on the `readable` event

jasnell pushed a commit that referenced this pull request Jul 10, 2015

docs:events clarify emitter.listener() behavior

f91fa52

Clarifies that emitter.listener() returns a copy, not a reference Resolves issue #9022 Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

jasnell pushed a commit that referenced this pull request Jul 10, 2015

Update util.markdown

423c433

Fix for #25559 (Typo in example of util.deprecate() documentation) Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

jasnell added a commit that referenced this pull request Jul 10, 2015

doc: additional refinement to readable event

6036e4f

Per #25635 (comment) Additional refinement to the clarification on the `readable` event Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25635

jasnell closed this Jul 10, 2015

orangemocha removed the in progress label Jul 10, 2015

jasnell pushed a commit to jasnell/node-joyent that referenced this pull request Jul 10, 2015

Update util.markdown

571ce9a

Fix for nodejs#25559 (Typo in example of util.deprecate() documentation) Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: nodejs#25635

jasnell added a commit that referenced this pull request Aug 4, 2015

doc: additional refinement to readable event

eda2560

Per #25635 (comment) Additional refinement to the clarification on the `readable` event Reviewed-By: James M Snell <jasnell@gmail.com> PR-URL: #25591

jasnell mentioned this pull request Aug 4, 2015

Cherrypick v0.12 doc updates nodejs/node#2302

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: several documentation improvements #25635

doc: several documentation improvements #25635

jasnell commented Jul 6, 2015

jasnell commented Jul 6, 2015

trevnorris Jul 6, 2015

jasnell Jul 6, 2015

trevnorris commented Jul 6, 2015

chrisdickinson Jul 6, 2015

jasnell Jul 9, 2015

jasnell Jul 9, 2015

jasnell commented Jul 10, 2015

doc: several documentation improvements #25635

doc: several documentation improvements #25635

Conversation

jasnell commented Jul 6, 2015

jasnell commented Jul 6, 2015

trevnorris Jul 6, 2015

Choose a reason for hiding this comment

jasnell Jul 6, 2015

Choose a reason for hiding this comment

trevnorris commented Jul 6, 2015

chrisdickinson Jul 6, 2015

Choose a reason for hiding this comment

jasnell Jul 9, 2015

Choose a reason for hiding this comment

jasnell Jul 9, 2015

Choose a reason for hiding this comment

jasnell commented Jul 10, 2015