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 golang#20825

Change-Id: I3a23c18c80c471c0caae3b4d2f6f8e547da0bed9
Reviewed-on: https://go-review.googlesource.com/46950
Reviewed-by: Brad Fitzpatrick <[email protected]>

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)
 }