Document event arguments (http2, maybe more)

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.

@grantila

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

Ping @nodejs/http2 to figure out next action here

@gireeshpunathil

@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.

@mcollina

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

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

Checklist for reference

Http2Session

Http2Stream

Final

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

doc,http2: add parameters for Http2Session:connect event

doc: add parameters for Http2Session:error event

doc: explain http2 aborted event callback

doc: improve doc Http2Stream: FrameError, Timeout and Trailers

@dev-313

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-313

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

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

@gireeshpunathil

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

@dev-313

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!

@gireeshpunathil

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

doc: improve doc Http2Stream: FrameError, Timeout and Trailers

Navigation Menu

Repository navigation

Document event arguments (http2, maybe more) #877

Http2Session

Http2Stream

Final

147 remaining items

Http2Session

Http2Stream

Final

Http2Session

Http2Stream

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Document event arguments (http2, maybe more) #877

Description

Activity

gireeshpunathil commented on Apr 2, 2018

gireeshpunathil commented on Apr 12, 2018

mcollina commented on Apr 12, 2018

ryzokuken commented on Apr 12, 2018

mcollina commented on Apr 12, 2018

ryzokuken commented on Apr 13, 2018

Http2Session

Http2Stream

Final

147 remaining items

gireeshpunathil commented on Dec 10, 2019

dev-script commented on Dec 11, 2019

dev-script commented on Dec 11, 2019

Http2Session

Http2Stream

Final

Http2Session

Http2Stream

dev-script commented on Dec 13, 2019

gireeshpunathil commented on Dec 13, 2019

dev-script commented on Dec 14, 2019

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions