Rollup merge of #37343 - bluss:write-doc, r=GuillaumeGomez

Add documentation for Read, Write impls for slices and Vec

The Write imps for &[u8] and Vec<u8> are quite different, and we need this to
be reflected in the docs.

These documentation comments will be visible on the respective type's
page in the trait impls section.

src/libstd/io/impls.rs

@@ -147,6 +147,10 @@ fn read_line(&mut self, buf: &mut String) -> io::Result<usize> {
 // =============================================================================
 // In-memory buffer implementations
 
+/// Read is implemented for `&[u8]` by copying from the slice.
+///
+/// Note that reading updates the slice to point to the yet unread part.
+/// The slice will be empty when EOF is reached.
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a> Read for &'a [u8] {
     #[inline]
@@ -180,6 +184,11 @@ fn fill_buf(&mut self) -> io::Result<&[u8]> { Ok(*self) }
     fn consume(&mut self, amt: usize) { *self = &self[amt..]; }
 }
 
+/// Write is implemented for `&mut [u8]` by copying into the slice, overwriting
+/// its data.
+///
+/// Note that writing updates the slice to point to the yet unwritten part.
+/// The slice will be empty when it has been completely overwritten.
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a> Write for &'a mut [u8] {
     #[inline]
@@ -204,6 +213,8 @@ fn write_all(&mut self, data: &[u8]) -> io::Result<()> {
     fn flush(&mut self) -> io::Result<()> { Ok(()) }
 }
 
+/// Write is implemented for `Vec<u8>` by appending to the vector.
+/// The vector will grow as needed.
 #[stable(feature = "rust1", since = "1.0.0")]
 impl Write for Vec<u8> {
     #[inline]