// 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)}
}