BufWriter: Make the soundness of BorrowedBuf usage clearer.

The previous safety comment was outdated as it was written before
`BorrowedBuf::set_init` was changed to be a boolean. It also failed
to address the possibility that `flush_buf` invalidated the
assumption.

Author: briansmith

library/std/src/io/copy.rs

@@ -221,7 +221,9 @@ impl<I: Write + ?Sized> BufferedWriterSpec for BufWriter<I> {
             let mut read_buf: BorrowedBuf<'_> = buf.spare_capacity_mut().into();
 
             if init {
-                // SAFETY: init is either 0 or the init_len from the previous iteration.
+                // SAFETY: `init` is only true after `reader` initializes `read_buf`,
+                // and is reset after each `flush_buf` in case `flush_buf` caused a
+                // re-allocation or any other kind of de-initialization.
                 unsafe { read_buf.set_init() };
             }
 
@@ -249,6 +251,11 @@ impl<I: Write + ?Sized> BufferedWriterSpec for BufWriter<I> {
                 }
             } else {
                 self.flush_buf()?;
+                // A less conservative alternative, if this causes performance issues, would be to
+                // enhance `flush_buf` to guarantee that it doesn't cause `self.buf` to reallocate
+                // or to de-initialize its spare capacity. (That may be possible as `flush_buf`
+                // never grows the buffer.)
+                init = false;
             }
         }
     }