io: ReadAtLeast: example does not produce the suggested error condition #36245
Description
I was using io.ReadAtLeast today to implement serial reads for some industrial control devices
and was reading the documentation when I noticed that the function definition for
io.ReadAtLeast was not aligned well with the example.
ReadAtLeast reads from r into buf until it has read at least min bytes. It returns the number of bytes copied and an error if fewer bytes were read. The error is EOF only if no bytes were read. If an EOF happens after reading fewer than min bytes, ReadAtLeast returns ErrUnexpectedEOF. If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer. On return, n >= min if and only if err == nil. If r returns an error having read at least min bytes, the error is dropped.
Focusing on the error condition for ErrUnexpectedEOF, this section of the example program
// minimal read size bigger than io.Reader stream
longBuf := make([]byte, 64)
if _, err := io.ReadAtLeast(r, longBuf, 64); err != nil {
fmt.Println("error:", err)
}is designed to demonstrate this error. However, r, the argument to io.ReadAtLeast in this part of the code, has already been used. So instead of this section of the example generating ErrUnexpectedEOF it just generates EOF.
I suggest that the example for ReadAtLeast be changed to the code at this playground example. https://play.golang.org/p/nWx28cfHB-G
Better still might be an example that demonstrates EOF, ErrUnexpectedEOF, and ErrShortbuffer. Happy to submit a PR to make the docs and examples more illustrative for the full range of error reporting!