io: clarify documentation for io.ByteReader on error values

Document that the byte value returned by ReadByte() is meaningless
if its error != nil. Because io.Reader and io.ByteReader are similar in
name, this CL aims to clear up any ambiguity surrounding the returned
values, particularly where io.Reader is allowed to return both a
non-zero number of valid bytes and err == EOF.

Fixes #20825

Change-Id: I3a23c18c80c471c0caae3b4d2f6f8e547da0bed9
Reviewed-on: https://go-review.googlesource.com/46950
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/io/io.go b/src/io/io.go
index 9e4b86594d8128d93ad406be78c2f3bcbcd365f4..28dab08e46cef187706e24fc976d25c5c04c3392 100644 (file)
--- a/src/io/io.go
+++ b/src/io/io.go
@@ -233,7 +233,9 @@ type WriterAt interface {
 
 // ByteReader is the interface that wraps the ReadByte method.
 //
-// ReadByte reads and returns the next byte from the input.
+// ReadByte reads and returns the next byte from the input or
+// any error encountered. If ReadByte returns an error, no input
+// byte was consumed, and the returned byte value is undefined.
 type ByteReader interface {
        ReadByte() (byte, error)
 }