bytes: note that NewBuffer's initial size can change

bytes.NewBuffer's documentation says it can be used to set the initial
size of the buffer. The current wording is:

> It can also be used to size the internal buffer for writing.

This may led users to believe that the buffer (its backing array) is
fixed in size and won't grow, which isn't true (subsequent Write calls
will expand the backing array as needed).

Change the doc to make it clearer that NewBuffer just sets the initial
size of the buffer.

Fixes #27242

Change-Id: I2a8cb5bee02ca2c1657ef59e2cf1434c7a9bd397
Reviewed-on: https://go-review.googlesource.com/132035
Reviewed-by: Dominik Honnef <dominik@honnef.co>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/bytes/buffer.go b/src/bytes/buffer.go
index a2eca2ed129bbf131b9ef6eccf480cf24eac65fb..14c5bc38d66890f8182cbd61d0337fa29335fbb5 100644 (file)
--- a/src/bytes/buffer.go
+++ b/src/bytes/buffer.go
@@ -441,9 +441,9 @@ func (b *Buffer) ReadString(delim byte) (line string, err error) {
 // NewBuffer creates and initializes a new Buffer using buf as its
 // initial contents. The new Buffer takes ownership of buf, and the
 // caller should not use buf after this call. NewBuffer is intended to
-// prepare a Buffer to read existing data. It can also be used to size
-// the internal buffer for writing. To do that, buf should have the
-// desired capacity but a length of zero.
+// prepare a Buffer to read existing data. It can also be used to set
+// the initial size of the internal buffer for writing. To do that,
+// buf should have the desired capacity but a length of zero.
 //
 // In most cases, new(Buffer) (or just declaring a Buffer variable) is
 // sufficient to initialize a Buffer.