bytes: Reader.Size method documentation is inaccurate

[kbolino]

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

Documentation issue; currently visible default version is 1.18.4

Does this issue reproduce with the latest release?

Yes, 1.18.4 is the latest release. This doesn't seem to have been fixed as of 1.19rc2 either.

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

N/A (platform-agnostic documentation issue)

What did you do?

Viewed the docs for Reader.Size method in bytes standard library package

What did you expect to see?

The Reader.Reset method can change the underlying byte slice. The docs for Size method should say something like (changes italicized):

Size returns the original length of the underlying byte slice. Size is the number of bytes available for reading via ReadAt. The returned value will not change between calls unless the byte slice is changed by Reset.

What did you see instead?

The docs currently say:

Size returns the original length of the underlying byte slice. Size is the number of bytes available for reading via ReadAt. The returned value is always the same and is not affected by calls to any other method.

The Reset method is the only violation of this wording, and it was added in Go 1.7, but the Size method dates back to 1.5. This minor documentation issue seems to have arisen because an assumption (immutability of the byte slice) changed between versions of the language/library.

[dsnet]

Your analysis looks right, we should update the documentation.

[gopherbot]

Change https://go.dev/cl/419237 mentions this issue: bytes: document that Reset method changes the return value of Size method