bufio: make the description of Peek's behavior better

Previously, based on the description, it was not obvious that Peek could
change the buffer. It may have been mistakenly assumed that Peek would
always return an error if n is greater than b.Buffered().

Change-Id: I095006dd2ba1c2138bb193396cb24e2dda42d771
GitHub-Last-Rev: 9d48f8ac81
GitHub-Pull-Request: golang/go#70712
Reviewed-on: https://go-review.googlesource.com/c/go/+/634175
Reviewed-by: Carlos Amedee <carlos@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Jorropo <jorropo.pgm@gmail.com>

src/bufio/bufio.go

@@ -133,9 +133,10 @@ func (b *Reader) readErr() error {
 }
 
 // Peek returns the next n bytes without advancing the reader. The bytes stop
-// being valid at the next read call. If Peek returns fewer than n bytes, it
-// also returns an error explaining why the read is short. The error is
-// [ErrBufferFull] if n is larger than b's buffer size.
+// being valid at the next read call. If necessary, Peek will read more bytes
+// into the buffer in order to make n bytes available. If Peek returns fewer
+// than n bytes, it also returns an error explaining why the read is short.
+// The error is [ErrBufferFull] if n is larger than b's buffer size.
 //
 // Calling Peek prevents a [Reader.UnreadByte] or [Reader.UnreadRune] call from succeeding
 // until the next read operation.