bytes.Buffer Write() should clearly document the buffer grows on demand

In /pkg/bytes/buffer.go, func (b *Buffer) Write(p []byte) should clearly document that
calling Write will always grow the buffer if needed.

Neither the function comment for Write nor the type comment for bytes.Buffer document
that the buffer grows on-demand. The documentation should make this clear.

Suggest changing the first sentence of the comment to read:
"Write appends the contents of p to the buffer growing the capacity if needed."

[robpike]

Comment 1:

It's a reasonable request but really, what else could it do?

[robpike]

Comment 2:

This issue was closed by revision 0359af4.

Status changed to Fixed.

Comment 3:

In my initial read of the docs I formed the (wrong) understanding that Buffer was a
fixed-capacity wrapper around a single unchanging byte array. I didn't read the type
comment closely enough to internalize that "variable-sized" meant "variable-capacity"
not "variably slices a fixed-capacity buffer."
The following sentence in the docstring led me astray: "If the buffer becomes too large,
Write will panic with ErrTooLarge." It is slightly unclear that the "too large" means
growing past some undefined limit. From the (incorrect) frame of thought that Buffer is
fixed-capacity, I read this as "don't exceed the fixed capacity or it'll panic."
Yes, in hindsight this is a totally bogus way to interpret it. But I actually coded
around this (perceived) limitation. So I filed this bug with the hope to improve the
docs so no one else makes the same mistake.
Maybe a one-word change to the panic phrasing would improve it:
"If the buffer grows too large, Write will panic with ErrTooLarge."
In that wording at least "grow" is mentioned in the docstring of the function that most
often grows the buffer.