os.File.ReadAt doc misleading

[hanwen]

The doc for ReadAt is somewhat misleading: 

"ReadAt reads len(b) bytes from the File starting at byte offset off. It returns
the number of bytes read and the Error, if any. EOF is signaled by a zero count with err
set to EOF. ReadAt always returns a non-nil Error when n != len(b)."

when EOF is encountered during  a read, you can have a > 0 return value and EOF.  How
about simply saying:

"ReadAt reads len(b) bytes from the File starting at byte offset off. It returns
the number of bytes read and if n != len(b) an error. End of file is signaled by the EOF
error."

[rsc]

Comment 1:

What is misleading about the current wording?

[hanwen]

Comment 2:

IMO it's not entirely clear what will happen if EOF falls in the middle of the slice
you're trying to read.

[hanwen]

Comment 3:

(that's an end-of-file condition while it comes with a non-zero read count.)

[hanwen]

Comment 4:

(that's an end-of-file condition while it comes with a non-zero read count.)

[gopherbot]

Comment 5 by Damir.Azdajic:

Took me a while to see it, but rephrased like this it should make sense what the
confusion is about (hopefullt):
If b is 8 bytes, and EOF happens at b[4], does:
a) ReadAt return 0, with err set to EOF
b) ReadAt return 4, with err set to EOF
c) ReadAt return 4, with err set to a non-nil value;
and on subsequent ReadAt attempts, it returns 0, with err set to EOF
The documentation states "EOF is signaled by a zero count with err set to EOF."
It makes it appear as if an EOF in the middle of a read causes ReadAt to abandon all
that it's read and just return 0.
Note: "func (*File) Read" of the same package has the same issue

[rsc]

Comment 6:

http://golang.org/cl/5417064

[rsc]

Comment 7:

This issue was closed by revision c69d634.

Status changed to Fixed.