doc: explain _writev() API #31356
doc: explain _writev() API #31356
Conversation
nodejs-github-bot
added
doc
|
This is rework of stalled PR #28690. |
There was a problem hiding this comment.
Looks good, and thanks for picking this up again!
I would suggest adding
Refs: https://github.com/nodejs/node/pull/28690
Co-authored-by: Parker Bjur <[email protected]>
to the commit message in order to include attribution for the previous PR that this continues from.
doc/api/stream.md
Outdated
| multiple chunks of data at once. If implemented, the method will be called with | ||
| all chunks of data currently buffered in the write queue. | ||
| multiple chunks of data at once. If implemented and if there are buffered data | ||
| from previous writes, `_writev` (that is capable of handling chunks of data) |
There was a problem hiding this comment.
I think the previous sentence implies that _writev() can handle chunks of data, and there’s no need to duplicate that:
| from previous writes, `_writev` (that is capable of handling chunks of data) | |
| from previous writes, `_writev` |
There was a problem hiding this comment.
@addaleax, Thanks. Fixed it.
the exact context of invocation of _writev API is not well known also, the choice between _write and _writev is not well known. add a description to make it explicit. Fixes: nodejs#28408 Refs: nodejs#28690 Co-authored-by: Parker Bjur <[email protected]>
HarshithaKP
force-pushed
the
writable_stream__writev
branch
from
e8d1197 to
e2f3c96
Compare
doc/api/stream.md
Outdated
| multiple chunks of data at once. If implemented, the method will be called with | ||
| all chunks of data currently buffered in the write queue. | ||
| multiple chunks of data at once. If implemented and if there are buffered data | ||
| from previous writes, `_writev` will be called instead of `_write`. |
There was a problem hiding this comment.
| from previous writes, `_writev` will be called instead of `_write`. | |
| from previous writes, `_writev()` will be called instead of `_write()`. |
There was a problem hiding this comment.
@Trott, thanks. Fixed it.
doc/api/stream.md
Outdated
| @@ -1886,8 +1886,8 @@ methods only. | |||
|
|
|||
| The `writable._writev()` method may be implemented in addition or alternatively | |||
| to `writable._write()` in stream implementations that are capable of processing | |||
| multiple chunks of data at once. If implemented, the method will be called with | |||
| all chunks of data currently buffered in the write queue. | |||
| multiple chunks of data at once. If implemented and if there are buffered data | |||
There was a problem hiding this comment.
Nit: "are buffered data" is correct (because the word data is plural) but treating data as a singular noun has become idiomatic, is generally considered correct too, and seems to be what we do in the docs. Treating data as a singular word is so common that "data are" sounds jarring to many people.
I am unable to find any other examples of "data" + "are" in our docs, but many "data" + "is":
buffer.md: "the data is zero-filled"
http2.md: "incoming data is not being read"
net.md: "when the data is finally" and "when data is received"
stream.md: "Writable streams are an abstraction for a destination to which data is..." and "Readable streams are an abstraction for a source from which data is..."
vm.md: "data is produced successfully"
...and many other examples.
Therefore, for consistency with the rest of the docs, I recommend switching this to "is":
| multiple chunks of data at once. If implemented and if there are buffered data | |
| multiple chunks of data at once. If implemented and if there is buffered data |
Trott
added
the
author ready
|
Landed in e47a1eb |
The exact context of invocation of _writev API is not well known. Also, the choice between _write and _writev is not well known. Add a description to make it explicit. Fixes: #28408 Refs: #28690 Co-authored-by: Parker Bjur <[email protected]> PR-URL: #31356 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]>
The exact context of invocation of _writev API is not well known. Also, the choice between _write and _writev is not well known. Add a description to make it explicit. Fixes: #28408 Refs: #28690 Co-authored-by: Parker Bjur <[email protected]> PR-URL: #31356 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]>
The exact context of invocation of _writev API is not well known. Also, the choice between _write and _writev is not well known. Add a description to make it explicit. Fixes: #28408 Refs: #28690 Co-authored-by: Parker Bjur <[email protected]> PR-URL: #31356 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]>
The exact context of invocation of _writev API is not well known. Also, the choice between _write and _writev is not well known. Add a description to make it explicit. Fixes: #28408 Refs: #28690 Co-authored-by: Parker Bjur <[email protected]> PR-URL: #31356 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]>
the exact context of invocation of _writev API is not well known
also, the choice between _write and _writev is not well known.
add a description to make it explicit.
Fixes: #28408
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes