Document event arguments (http2, maybe more)

[grantila]

• Scope (install, code, runtime, meta, other?):
  Documentation

• Module (and version) (if relevant):
  http2

When reading through parts of the http2 documentation, I'm missing information about what arguments are passed in many events. It's like documenting that there's a function called foo but not what argument it takes.

If an event is emitted without any arguments, writing "Emitted without any arguments" in the documentation would be helpful. I tend to console.log(arguments) just to see what's there, and this forces me to try to cause events to actually be emitted... I'm probably not the only one.

session:close 😟 I'm guessing none?
session:connect 😟 None? Also, what will I typically listen to?
session:error 😧 An error argument perhaps? No?
session:frameError 😉 Well documented! But, the argument types have a different layout compared with:
session:goaway 👍
session:localSettings 😕 What properties can I expect?
session:remoteSettings 😕 What properties can I expect?
session:stream 😔 Flags? This is my flag: 🇸🇪
session:socketError 😰 What am I supposed to do?
session:timeout 😒 Doesn't look like any arguments by the example snippet. And should I expect Node to close the socket?

The same goes for the streams...

stream:aborted 😶 "Writable end". Is that my end, or the remote peers? Is abortion an error, i.e. should I expect an argument?
stream:error 🤒 No argument in an error event. Or? Probably there is one...
stream:frameError 🤔 Interesting...
stream:streamClosed 🤗 Actually useful description, since it describes how this event relates to the flow of other events.
stream:timeout 🙁 What, am I supposed to do? I read the doc for setTimeout and it seems I should manually perform things in this event handler...
stream:trailers 😂 More flags! 🏳️‍🌈

I realize http2 is in early stage. But for early adopters and testers, this kind of information is very useful if it is provided. I've seen this lack of information before in other modules, so probably the documentation needs an overhaul of the events specifically, with exactly what is being sent.

[gireeshpunathil]

@grantila - is this still outstanding? are you in a position to contribute to the improvement on the documentation?

[gireeshpunathil]

Ping @nodejs/http2 to figure out next action here

[mcollina]

@gireeshpunathil it would be fantastic if someone went through that list and opened issues (maybe with good-first-contribution label) for all of the events that are missing.

[ryzokuken]

@mcollina I could try opening a few by this weekend.

[mcollina]

awesome! Remember to tag @nodejs/http2 in all of them.

[ryzokuken]

Checklist for reference

Http2Session

• session:close
• session:connect
• session:error
• session:frameError
• session:goaway
• session:localSettings
• session:remoteSettings
• session:stream
• session:socketError
• session:timeout

Http2Stream

• stream:aborted
• stream:error
• stream:frameError
• stream:streamClosed
• stream:timeout
• stream:trailers

Final

• Final cleanup PR that cleans up the docs and makes all the argument listings consistent. Resolves this issue.

[dev-script]

I want to work on all pending issues. Please allow me. Thanks

[dev-script]

Unable to find stream:streamClosed event. Above mentioned link open Node.js v8.16.2 Documentation page.

[gireeshpunathil]

Looks like this got closed because of the Fixes tag in nodejs/node#30373

@dev-313 - can you pls confirm all the items that are listed in the checklist (#877 (comment)) are covered? If not, are you going to plan to work on those?

Keeping it open until then.

[dev-script]

Looks like this got closed because of the Fixes tag in nodejs/node#30373

@dev-313 - can you pls confirm all the items that are listed in the checklist (#877 (comment)) are covered? If not, are you going to plan to work on those?

Keeping it open until then.

ok @gireeshpunathil

[dev-script]

Checklist for reference

Http2Session

* [x]  session:close

* [x]  session:connect

* [x]  session:error

* [x]  session:frameError

* [x]  session:goaway

* [x]  session:localSettings

* [x]  session:remoteSettings

* [x]  session:stream

* [ ]  ~session:socketError~

* [ ]  session:timeout

Http2Stream

* [ ]  stream:aborted

* [ ]  stream:error

* [ ]  stream:frameError

* [ ]  stream:streamClosed

* [ ]  stream:timeout

* [ ]  stream:trailers

Final

* [ ]  Final cleanup PR that cleans up the docs and makes all the argument listings consistent. Resolves this issue.

Checklist for remaining tasks

Http2Session

• session:timeout

Http2Stream

• stream:aborted

• stream:error (Https2Stream 'error' event same as Https2Session so i think no need to change.)

• stream:frameError

• stream:streamClosed (it might have been removed.)

• stream:timeout

• stream:trailers

[dev-script]

@gireeshpunathil All remaining tasks are completed but can you please help me to understand last task "Final PR".

[gireeshpunathil]

thanks @dev-313 (and others) for doing this!

Final PR as referred in #877 (comment) would mean to go through the http2.md doc and making sure the doc text is consistent (wordings, construct, style etc.) and if not, make so. I don't think we need to hold up this issue for that; so will close this. If you find anything that needs change, please go ahead a raise a PR; or else, that is it!

thanks again!

[dev-script]

Thanks @gireeshpunathil. If i find anything that need change, I'll raise a PR.