From: Martin Sucha <anty.sk+git@gmail.com>
Date: Tue, 22 Feb 2022 20:51:04 +0000 (+0100)
Subject: net: document methods of Buffers
X-Git-Tag: go1.18~33^2~30
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=35170365c83085024e4855c14032599f5513d563;p=gostls13.git

net: document methods of Buffers

There is code in the wild that copies the Buffers slice,
but not the contents.
Let's document explicitly that it is not safe to do so.

Updates #45163

Change-Id: Id45e27b93037d4e9f2bfde2558e7869983b60bcf
Reviewed-on: https://go-review.googlesource.com/c/go/+/387434
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>
---

diff --git a/src/net/net.go b/src/net/net.go
index 77e54a9125..d91e743a01 100644
--- a/src/net/net.go
+++ b/src/net/net.go
@@ -703,6 +703,12 @@ var (
 	_ io.Reader   = (*Buffers)(nil)
 )
 
+// WriteTo writes contents of the buffers to w.
+//
+// WriteTo implements io.WriterTo for Buffers.
+//
+// WriteTo modifies the slice v as well as v[i] for 0 <= i < len(v),
+// but does not modify v[i][j] for any i, j.
 func (v *Buffers) WriteTo(w io.Writer) (n int64, err error) {
 	if wv, ok := w.(buffersWriter); ok {
 		return wv.writeBuffers(v)
@@ -719,6 +725,12 @@ func (v *Buffers) WriteTo(w io.Writer) (n int64, err error) {
 	return n, nil
 }
 
+// Read from the buffers.
+//
+// Read implements io.Reader for Buffers.
+//
+// Read modifies the slice v as well as v[i] for 0 <= i < len(v),
+// but does not modify v[i][j] for any i, j.
 func (v *Buffers) Read(p []byte) (n int, err error) {
 	for len(p) > 0 && len(*v) > 0 {
 		n0 := copy(p, (*v)[0])