At the moment, documentation of std::io::Write::write indicates that
call to it ‘represents at most one attempt to write to any wrapped
object’.  It seems that such wording was put there to contrast it
with pre-1.0 interface which attempted to write all the data (it has
since been changed in [RFC 517]).

However, the requirement puts unnecessary constraints and may complicate
adaptors which perform non-trivial transformations on the data.  For
example, they may maintain an internal buffer which needs to be written
out before the write method accepts more data.  It might be natural to
code the method such that it flushes the buffer and then grabs another
chunk of user data.  With the current wording in the documentation, the
adaptor would be forced to return Ok(0).

This commit softens the wording such that implementations can choose
code structure which makes most sense for their particular use case.

While at it, elaborate on the meaning of `Ok(0)` return pointing out
that the write_all methods interprets it as an error.

[RFC 517]: https://rust-lang.github.io/rfcs/0517-io-os-reform.html

Co-authored-by: Andrew Gallant <jamslam@gmail.com>

Co-authored-by: Jacob Lifshay <programmerjake@gmail.com>