internal: Improve documentation around buffer.Unbounded (#3241)

internal/buffer/unbounded.go

@@ -26,6 +26,13 @@ import "sync"
 //
 // All methods on this type are thread-safe and don't block on anything except
 // the underlying mutex used for synchronization.
+//
+// Unbounded supports values of any type to be stored in it by using a channel
+// of `interface{}`. This means that a call to Put() incurs an extra memory
+// allocation, and also that users need a type assertion while reading. For
+// performance critical code paths, using Unbounded is strongly discouraged and
+// defining a new type specific implementation of this buffer is preferred. See
+// internal/transport/transport.go for an example of this.
 type Unbounded struct {
 	c       chan interface{}
 	mu      sync.Mutex

internal/transport/transport.go

@@ -73,10 +73,11 @@ type recvMsg struct {
 }
 
 // recvBuffer is an unbounded channel of recvMsg structs.
-// Note recvBuffer differs from controlBuffer only in that recvBuffer
+//
-// holds a channel of only recvMsg structs instead of objects implementing "item" interface.
+// Note: recvBuffer differs from buffer.Unbounded only in the fact that it
-// recvBuffer is written to much more often than
+// holds a channel of recvMsg structs instead of objects implementing "item"
-// controlBuffer and using strict recvMsg structs helps avoid allocation in "recvBuffer.put"
+// interface. recvBuffer is written to much more often and using strict recvMsg
+// structs helps avoid allocation in "recvBuffer.put"
 type recvBuffer struct {
 	c       chan recvMsg
 	mu      sync.Mutex