more docs for stream fncs
@@ -28,6 +28,13 @@ type MuxedStream interface {
//
// Close may be asynchronous and _does not_ guarantee receipt of the
// data.
+ //
+ // Close closes the stream for both reading and writing.
+ // Close is equivalent to calling `CloseRead` and `CloseWrite`. Importantly, Close will not wait for any form of acknowledgment.
+ // If acknowledgment is required, the caller must call `CloseWrite`, then wait on the stream for a response (or an EOF),
+ // then call Close() to free the stream object.
+ //
+ // When done with a stream, the user must call either Close() or `Reset()` to discard the stream, even after calling `CloseRead` and/or `CloseWrite`.
io.Closer
// CloseWrite closes the stream for writing but leaves it open for
@@ -40,6 +47,11 @@ type MuxedStream interface {
// CloseRead closes the stream for reading but leaves it open for
// writing.
//
+ // When CloseRead is called, all in-progress Read calls are interrupted with a non-EOF error and
+ // no further calls to Read will succeed.
+ //
+ // The handling of new incoming data on the stream after calling this function is implementation defined.
+ //
// CloseRead does not free the stream, users must still call Close or
// Reset.
CloseRead() error
