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.

Sign up for GitHub

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

doc: explain _writev() API #31356

Closed
wants to merge 2 commits into from
Closed

doc: explain _writev() API #31356

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e2f3c96
doc: explain _writev() API
HarshithaKP Jan 14, 2020
ece288d
fixup: address review comments
HarshithaKP Jan 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions doc/api/stream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

@Trott Trott Jan 16, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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":

Suggested change
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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Trott, done.

from previous writes, `_writev` will be called instead of `_write`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
from previous writes, `_writev` will be called instead of `_write`.
from previous writes, `_writev()` will be called instead of `_write()`.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Trott, thanks. Fixed it.


The `writable._writev()` method is prefixed with an underscore because it is
internal to the class that defines it, and should never be called directly by
Expand Down