add documentation what Close and Reset are supposed to do

[marten-seemann]

Reset was recently (be2992b) added to the Stream interface, but it's not clear what the expected behavior is.

We should describe that in the interface. Furthermore, Close is also an ambiguous term, and needs an explanation as well.

For example in QUIC, Close closes the stream in the write-direction, and Reset closes the stream in read-direction.

[Stebalien]

For example in QUIC, Close closes the stream in the write-direction, and Reset closes the stream in read-direction.

This. @whyrusleeping added this method because yamux has this same behavior and it turns out we've been half-closing our streams. This often didn't make a difference but was the ultimate cause of a rather nasty bitswap bug (ipfs/kubo#3651 (comment)).

[marten-seemann]

That's great news! Having matching interfaces here will reduce a lot of friction with the QUIC integration I've been working on.