From: Rob Pike <r@golang.org>
Date: Fri, 26 Aug 2011 05:09:23 +0000 (+1000)
Subject: bytes.Buffer: clarify that NewBuffer is not for beginners
X-Git-Tag: weekly.2011-09-01~71
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=a45c657db1b6ce6689ddedab6ff88c0380901379;p=gostls13.git

bytes.Buffer: clarify that NewBuffer is not for beginners

R=golang-dev, adg
CC=golang-dev
https://golang.org/cl/4965048
---

diff --git a/src/pkg/bytes/buffer.go b/src/pkg/bytes/buffer.go
index 5de86105d0..975031bfa4 100644
--- a/src/pkg/bytes/buffer.go
+++ b/src/pkg/bytes/buffer.go
@@ -336,13 +336,18 @@ func (b *Buffer) ReadString(delim byte) (line string, err os.Error) {
 
 // NewBuffer creates and initializes a new Buffer using buf as its initial
 // contents.  It 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,
+// 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.
+//
+// In most cases, new(Buffer) (or just declaring a Buffer variable) is
+// preferable to NewBuffer.  In particular, passing a non-empty buf to
+// NewBuffer and then writing to the Buffer will overwrite buf, not append to
+// it.
 func NewBuffer(buf []byte) *Buffer { return &Buffer{buf: buf} }
 
 // NewBufferString creates and initializes a new Buffer using string s as its
 // initial contents.  It is intended to prepare a buffer to read an existing
-// string.
+// string.  See the warnings about NewBuffer; similar issues apply here.
 func NewBufferString(s string) *Buffer {
 	return &Buffer{buf: []byte(s)}
 }