io: soften ‘at most one write attempt’ requirement in io::Write::write

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

Author: mina86

library/std/src/io/mod.rs

@@ -1385,17 +1385,18 @@ pub trait Write {
     ///
     /// This function will attempt to write the entire contents of `buf`, but
     /// the entire write might not succeed, or the write may also generate an
-    /// error. A call to `write` represents *at most one* attempt to write to
+    /// error. Typically, a call to `write` represents one attempt to write to
     /// any wrapped object.
     ///
     /// Calls to `write` are not guaranteed to block waiting for data to be
     /// written, and a write which would otherwise block can be indicated through
     /// an [`Err`] variant.
     ///
-    /// If the return value is [`Ok(n)`] then it must be guaranteed that
-    /// `n <= buf.len()`. A return value of `0` typically means that the
-    /// underlying object is no longer able to accept bytes and will likely not
-    /// be able to in the future as well, or that the buffer provided is empty.
+    /// If the return value is [`Ok(n)`] then it must be guaranteed that `n <=
+    /// buf.len()`. Unless `input` is empty, this function shouldn’t return `0`
+    /// since caller may interpret that as an error (the default implementation
+    /// of [`Write::write_all`] does exactly that).  To indicate lack of space
+    /// function should return [`ErrorKind::StorageFull`] error instead.
     ///
     /// # Errors
     ///