Documentation for io::Read::read's return value #70360

As far as I know File uses libc::read on unix for its Read implementation. The read method returns the amount of bytes that were read to the given buffer. libc::read's man page says the following:

It is not an error if this number is smaller than the number of bytes requested; this may happen for example because fewer bytes are actually available right now (maybe because we were close to end-of-file, or because we are reading from a pipe, or from a terminal), or because read() was interrupted by a signal.

I think the documentation for io::Read doesn't currently make it clear that the returned value can be less than the buffer size, even when the reader is not at the end of the stream. While this behaviour may seem obvious to anyone familiar with libc, it should still be documented, as it's not obvious for those coming from other languages, and it can be important in some cases.