Rollup merge of rust-lang#107200 - mina86:c, r=Amanieu

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

library/std/src/io/mod.rs

@@ -1416,17 +1416,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 this method consumed `n > 0` bytes of `buf` it must return [`Ok(n)`].
+    /// If the return value is `Ok(n)` then `n` must satisfy `n <= buf.len()`.
+    /// Unless `buf` is empty, this function shouldn’t return `Ok(0)` since the
+    /// caller may interpret that as an error.  To indicate lack of space,
+    /// implementors should return [`ErrorKind::StorageFull`] error instead.
     ///
     /// # Errors
     ///