doc: error modes of writable #29745

ronag · 2019-09-28T07:40:16Z

Documents the error modes of Writable

Checklist

documentation is changed or added
commit message follows commit guidelines

doc/api/stream.md

Co-Authored-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

Trott · 2019-10-01T03:56:49Z

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3948/

doc/api/stream.md

Co-Authored-By: Rich Trott <rtrott@gmail.com>

ronag · 2019-11-24T09:56:44Z

Could this get another review from nodejs/streams?

Trott · 2019-11-24T17:16:23Z

@nodejs/streams

mcollina · 2019-11-24T18:07:20Z

doc/api/stream.md

@@ -432,6 +432,18 @@ file.end('world!');
 // Writing more now is not allowed!
 ```

+[`stream.end()`][stream-end] will error with (in order of precedence):


Can you clarify if it will throw or emit an error?

How about now?

mcollina · 2019-11-24T18:07:35Z

doc/api/stream.md

@@ -619,6 +631,14 @@ write('hello', () => {

 A `Writable` stream in object mode will always ignore the `encoding` argument.

+`stream.write()` will error with (in order of precedence):


doc/api/stream.md

Co-Authored-By: Yorkie Liu <yorkiefixer@gmail.com>

yorkie · 2019-11-24T19:47:03Z

doc/api/stream.md

@@ -619,6 +632,15 @@ write('hello', () => {

 A `Writable` stream in object mode will always ignore the `encoding` argument.

+`stream.write()`  will call it's callback and emit `'error'`


Suggested change

`stream.write()` will call it's callback and emit `'error'`

`stream.write()` will call its callback and emit `'error'`

doc/api/stream.md

Co-Authored-By: Denys Otrishko <9109612+lundibundi@users.noreply.github.com>

yorkie · 2019-11-24T20:01:34Z

This PR seems to document how does the write/end methods emit the errors, it's a bit more easy to be changed in somehow and without changing this docs, if we would have links to functions, it will feel less.

ronag · 2019-11-24T20:07:09Z

This PR seems to document how does the write/end methods emit the errors, it's a bit more easy to be changed in somehow and without changing this docs, if we would have links to functions, it will feel less.

Sorry, I don't understand. Do you think you could try to rephrase?

yorkie · 2019-11-24T20:14:17Z

Sorry, I don't understand. Do you think you could try to rephrase?

Never mind, I'm not proposing any changes on this PR. FYI, I was considering that it's easy to forget to update here when someone changed the algorithm of write/end in our streams.

ronag · 2019-12-01T18:51:59Z

@yorkie @lundibundi Can this PR get your approvals and maybe land?

doc/api/stream.md

lundibundi · 2019-12-01T19:09:01Z

ping @mcollina

Co-Authored-By: Denys Otrishko <9109612+lundibundi@users.noreply.github.com>

lundibundi · 2019-12-01T19:14:55Z

LiteCI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/4094/

ronag · 2019-12-29T19:50:31Z

Currently blocked by whatever happens with #29197 which affects some details of this.

BridgeAR · 2020-01-12T01:57:49Z

This needs a rebase.

ronag · 2020-02-14T09:39:18Z

The error modes of streams is still a fluid situation so I think it's better re-open this at a future stage.

nodejs-github-bot added doc Issues and PRs related to the documentations. stream Issues and PRs related to the stream subsystem. labels Sep 28, 2019

ronag changed the title ~~doc: document error modes of writable.write~~ doc: error modes of writable.write Sep 28, 2019

ronag force-pushed the doc-write-errors branch 4 times, most recently from 6c6beba to b2c4f5a Compare September 28, 2019 08:11

ronag changed the title ~~doc: error modes of writable.write~~ doc: error modes of writable Sep 28, 2019

ronag force-pushed the doc-write-errors branch 5 times, most recently from 5e422d0 to b030cf2 Compare September 28, 2019 10:03

ronag commented Sep 28, 2019

View reviewed changes