Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

stream,doc: require finished callback and add options docs #21058

Closed

Conversation

@BridgeAR
Copy link
Member

BridgeAR commented May 31, 2018

I just stumbled upon missing documentation about the Stream.finished() options. We should also make the callback mandatory as already documented. Right now there would be a no op added in case a falsy value is provided for the callback.

Test cases are missing and I'll add some later on (if someone wants to add them, I am also more than happy about that ;-) please feel free to just directly pushing on this branch).

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • tests and/or benchmarks are included
  • documentation is changed or added
  • commit message follows commit guidelines
Copy link
Member

Trott left a comment

Content LGTM. Some formatting/grammar changes requested.

<!-- YAML
added: v10.0.0
-->

* `stream` {Stream} A readable and/or writable stream.
* `options` {Object}
* `error` {boolean} If set to `false` a call to emit('error', err) is not

This comment has been minimized.

Copy link
@Trott

Trott May 31, 2018

Member

Comma after `false`, and maybe then as well:

If set to `false`, then a call to ...

This comment has been minimized.

Copy link
@Trott

Trott May 31, 2018

Member

Backticks around emit('error', err)

<!-- YAML
added: v10.0.0
-->

* `stream` {Stream} A readable and/or writable stream.
* `options` {Object}
* `error` {boolean} If set to `false` a call to emit('error', err) is not
treated finished. **Default**: `true`.

This comment has been minimized.

Copy link
@Trott

Trott May 31, 2018

Member

Missing word or something. treated as finished perhaps?

* `options` {Object}
* `error` {boolean} If set to `false` a call to emit('error', err) is not
treated finished. **Default**: `true`.
* `readable` {boolean} When set to `false` the callback will be called after

This comment has been minimized.

Copy link
@Trott

Trott May 31, 2018

Member

Same thing with the comma and probably a then as well.

* `readable` {boolean} When set to `false` the callback will be called after
the stream ended but the stream might still be readable. **Default**:
`true`.
* `writable` {boolean} When set to `false` the callback will be called after

This comment has been minimized.

Copy link
@Trott

Trott May 31, 2018

Member

Same thing with the comma and probably a then as well.

* `error` {boolean} If set to `false` a call to emit('error', err) is not
treated finished. **Default**: `true`.
* `readable` {boolean} When set to `false` the callback will be called after
the stream ended but the stream might still be readable. **Default**:

This comment has been minimized.

Copy link
@Trott

Trott May 31, 2018

Member

ended -> ends

the stream ended but the stream might still be readable. **Default**:
`true`.
* `writable` {boolean} When set to `false` the callback will be called after
the stream ended but the stream might still be writable. **Default**:

This comment has been minimized.

Copy link
@Trott

Trott May 31, 2018

Member

ended -> ends

@nodejs nodejs deleted a comment from refack Jun 1, 2018
@vsemozhetbyt

This comment has been minimized.

Copy link
Contributor

vsemozhetbyt commented Jun 2, 2018

When we change a heading in the docs, we need to check if there are links to this heading in all the docs (copy the old hash from the old HTML doc and grep this hash in *.md sources). Currently, this one link in stream.md also need to be updated:

https://github.com/nodejs/node/blame/master/doc/api/stream.md#L2504

@mafintosh

This comment has been minimized.

Copy link
Member

mafintosh commented Jun 5, 2018

LGTM on the changes mentioned from me

Copy link
Member

mcollina left a comment

LGTM

BridgeAR added 3 commits May 31, 2018
Make the callback mandatory as mostly done in all other Node.js
callback APIs so users explicitly have to decide what to do in error
cases.
When originally implemented it was missed that Stream.finished() has
an optional options object. This adds the docs to those.
@BridgeAR BridgeAR force-pushed the BridgeAR:require-end-of-stream-callback branch from 27c3883 to c310236 Aug 20, 2018
@BridgeAR BridgeAR requested a review from nodejs/tsc Aug 20, 2018
@BridgeAR

This comment has been minimized.

Copy link
Member Author

BridgeAR commented Aug 20, 2018

@Trott @nodejs/streams PTAL

I addressed the comments and added some tests.

CI https://ci.nodejs.org/job/node-test-pull-request/16622/

@Trott Trott dismissed their stale review Aug 21, 2018

formatting/grammar fixed

@mcollina

This comment has been minimized.

Copy link
Member

mcollina commented Aug 21, 2018

Still LGTM, this can land.

@BridgeAR

This comment has been minimized.

Copy link
Member Author

BridgeAR commented Aug 21, 2018

@mafintosh

This comment has been minimized.

Copy link
Member

mafintosh commented Aug 21, 2018

@BridgeAR still lgtm

BridgeAR added a commit to BridgeAR/node that referenced this pull request Aug 21, 2018
Make the callback mandatory as mostly done in all other Node.js
callback APIs so users explicitly have to decide what to do in error
cases.

This also documents the options for `Stream.finished()`.

When originally implemented it was missed that Stream.finished() has
an optional options object.

PR-URL: nodejs#21058
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Mathias Buus <mathiasbuus@gmail.com>
@BridgeAR

This comment has been minimized.

Copy link
Member Author

BridgeAR commented Aug 21, 2018

Landed in 36468ca 🎉

@BridgeAR BridgeAR closed this Aug 21, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.