bytes: NewBuffer documentation error

[tebeka]

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

go version go1.11 linux/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

GOARCH="amd64"
GOBIN=""
GOCACHE="/home/miki/.cache/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/miki/work/iguazio"
GOPROXY=""
GORACE=""
GOROOT="/opt/go"
GOTMPDIR=""
GOTOOLDIR="/opt/go/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build378279576=/tmp/go-build -gno-record-gcc-switches"

What did you do?

bytes.NewBuffer documentation says:

... 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.

However when I try to create such buffer and write more than the initial capacity - the buffer just grow.

See https://play.golang.org/p/-iCudrjewno

What did you expect to see?

An error or writer block

What did you see instead?

Buffer grows as much as needed.

[ALTree]

An error or writer block

Why? That part of NewBuffer's documentation is talking about the initial capacity of the backing buffer.

Later on you call Write in a loop and Write is explicitly documented to grow the buffer as needed:

Write appends the contents of p to the buffer, growing the buffer as needed.

[ALTree]

I mean we could change NewBuffer doc from

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

to

It can also be used to set the initial size of the internal buffer for writing.

to make completely clear that we're talking about the initial size, I guess...

[tebeka]

@ALTree

It can also be used to set the initial size of the internal buffer for writing.

This seems great

[gopherbot]

Change https://golang.org/cl/132035 mentions this issue: bytes: note that NewBuffer's initial size can grow