doc: multiple improvements in Stream docs

[estliberitas]

Add links, fix constants and functions styling. Minor lexical corrections.

[chrisdickinson]

Could you change this method to the _read() implementation?

[chrisdickinson]

Great work! Once the wording nit is corrected, this LGTM. We usually leave PRs open once they've been LGTM'd for about 48 hours to make sure all of the contributors get a chance to review. If no one has objections it should be merged shortly after that. Thanks for the contribution!

[thefourtheye]

Can't we simply say 'it returns'?

[estliberitas]

@thefourtheye BTW, I was wondering. In this file there are a lot of duplicates and in others which I worked on too. Maybe replace those where possible by some default except places where arguments matter to the context of sentences (like "for this case use read(0)"). If so, what would be default stream.write(), write() or smth. different? I find stream.write() more appropriate because it equals to name of header where this method is described
P.S. would be cool to create some kind of doc style guide or it already exists?

[thefourtheye]

@estliberitas Yes, I was about to talk to you about the same (I couldn't earlier because I was on Mobile). What we probably can do is, use stream.write and stream.read consistently. And whenever we see the call with specific arguments, we can say something like "for this case use [stream.read()][] with 0". May be we can add a small description about the parameter being passed. What do you think?

[estliberitas]

@thefourtheye Well, I find it a good idea. And as for multiple arguments, we just separate by comma? Like, for example, lines 1582-1583:

A Writable stream in object mode will always ignore the encoding
argument to stream.write() when called with chunk, encoding.

To me it's not so cool, but at least it's informative and saves us from copy-pasting a lot.

Other concern is optional arguments:

Note that calling stream.read() with [size] after the 'end' event has
been triggered will return null. No runtime error will be raised.

[estliberitas]

@thefourtheye Other idea would be patch doc tool to look for links without arguments 😉

[thefourtheye]

Or we can use a common name like this [stream.read(0)][stream-read] and then we can tag all the links with various arguments with [stream-read]

[estliberitas]

@thefourtheye Wow, I got something new today. Thanks, I think that resolves all the questions above.

[estliberitas]

@chrisdickinson @thefourtheye Guys, please check once have a time.

To simplify life I made a small script to check links consistency: https://gist.github.com/estliberitas/bfd35c7a5a977aa5d221

[thefourtheye]

Sweeeet :-)

[estliberitas]

Btw, seems I did same thing as in #5003 and #5007

Also, I used that script from Gist above for other files, and it seems there are things to do yet for other API doc files.

[Qard]

LGTM

[thefourtheye]

it seems there are things to do yet for other API doc files

Please go ahead and submit PRs. I always wanted to clean this thing myself. Glad you are doing this :-)

[thefourtheye]

LGTM

[estliberitas]

@thefourtheye will do ;)

[jasnell]

@estliberitas ... there have been some other changes that touch on the same file, can I ask you to rebase this and update so we can remove the duplication? Thank you!

[estliberitas]

Yep, I guess it's #5007, ok will do now.

[estliberitas]

@jasnell done

[jasnell]

LGTM. Thank you!

[jasnell]

Landed in b0b4aeb