From 36ca8828cb5fb76a2a9b6c821f7d7ca18e9e83bc Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sun, 22 Feb 2026 09:51:18 +0800
Subject: bufpool: Document how .Bytes is intended to be used

---
 internal/bufpool/buffers.go | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'internal/bufpool')

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
-- 
cgit v1.3.1-10-gc9f91