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