Rollup merge of rust-lang#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.

Author: GuillaumeGomez

src/libstd/io/impls.rs

@@ -147,6 +147,10 @@ impl<B: BufRead + ?Sized> BufRead for Box<B> {
 // =============================================================================
 // 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 @@ impl<'a> BufRead for &'a [u8] {
     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 @@ impl<'a> Write for &'a mut [u8] {
     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]