os: improve file.Read method description

[btracey]

The current description for file.Read is 

"Read reads up to len(b) bytes from the File. It returns the number of bytes read
and an error, if any. EOF is signaled by a zero count with err set to io.EOF."

I found the second sentence confusing. I read it to mean "If the end of the file is
reached, n will be set to zero and err will be set to io.EOF" which is not the
actual behavior. Could you change the wording to be something like 

"Read reads up to len(b) bytes from the File. It returns the number of bytes read
and an error, if any occurred. If the end of the file is reached, the number of bytes
read will be less than the length of the buffer. The buffer will not be truncated. If no
bytes are read, err is set to io.EOF, otherwise no error will be signaled"

[bradfitz]

Comment 1:

This could be clarified, but your sentence "The buffer will not be truncated." doesn't
make much since, since the caller owns the slice.  The File.Read method doesn't get a
pointer to the slice, so it wouldn't even be possible for the Read method to truncate it.
For reference, the io.Reader docs are more clear: http://tip.golang.org/pkg/io/#Reader
What's not clear is whether the File.Read docs are trying to promise a tighter contract
than io.Reader.Read itself.

Labels changed: added documentation.

[btracey]

Comment 2:

Good point on the buffer. You are right, that clarification is unnecessary.
The io.Reader description is better. Perhaps file could link to that description and
explicitly state the fact that no io.EOF error is returned when n > 0 (the io
description specifies that either may happen).
Perhaps this should be a different issue, but I'm confused by " and callers should treat
that situation as a no-op" that is the last sentence of the io.Reader description. Is
that just saying there should be a check like
if bytesLeftInReader == 0{
    return 0, io.EOF
}
?

[rsc]

Comment 3:

Labels changed: added go1.3maybe.

[rsc]

Comment 4:

Labels changed: added release-none, removed go1.3maybe.

[rsc]

Comment 5:

Labels changed: added repo-main.

[gopherbot]

CL https://golang.org/cl/22220 mentions this issue.

[gopherbot]

CL https://golang.org/cl/32102 mentions this issue.