bufpool: Document how .Bytes is intended to be used

1 files changed, 6 insertions, 0 deletions

diff --git a/internal/bufpool/buffers.go b/internal/bufpool/buffers.go
index 19e3f80a..cb86b17e 100644
--- a/internal/bufpool/buffers.go
+++ b/internal/bufpool/buffers.go
@@ -25,6 +25,12 @@ const (
 // Buffers must not be copied after first use; doing so can cause double-returns
 // to the pool and data races.
 //
+// In general, pass Buffer around when used internally, and directly .Bytes() when
+// returning output across our API boundary. It is neither necessary nor efficient
+// to copy/append the .Bytes() to a newly-allocated slice; in cases where we do
+// want the raw byte slice out of our API boundary, it is perfectly acceptable to
+// simply not call Release().
+//
 //go:nocopy
 type Buffer struct {
 	_    struct{} // for nocopy