bufio: suggest io.ReadFull at (*Reader).Read

Many times when using bufio.Reader I imagine, incorrectly, that it
implements the retry loop itself, being a high-level buffered wrapper
around, say, a file descriptor prone to short reads. This comment
would have saved me much time.

Change-Id: I34c790e0d7c1515430a76d02ce4739b586a36ba7
Reviewed-on: https://go-review.googlesource.com/c/145577
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/bufio/bufio.go b/src/bufio/bufio.go
index 8d162b34a06773a4a586f26a5cf5d4b0ed3a6aeb..e498dfea1ed161dc3613260d1ae11e9a5bb32c27 100644 (file)
--- a/src/bufio/bufio.go
+++ b/src/bufio/bufio.go
@@ -187,6 +187,8 @@ func (b *Reader) Discard(n int) (discarded int, err error) {
 // The bytes are taken from at most one Read on the underlying Reader,
 // hence n may be less than len(p).
 // At EOF, the count will be zero and err will be io.EOF.
+//
+// To read exactly len(p) bytes, use io.ReadFull(b, p).
 func (b *Reader) Read(p []byte) (n int, err error) {
        n = len(p)
        if n == 0 {