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 77e54a91258e14997615d3fc6e88a27afb58333d..d91e743a014e21c7b586b733fb731868bf9c49d5 100644 (file)
--- 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])