Update documentation for AsyncRead and AsyncWrite (#596)

tokio-io: update documentation for AsyncRead and AsyncWrite

tokio-io/src/async_read.rs

@@ -16,15 +16,16 @@ use split::{ReadHalf, WriteHalf};
 /// Specifically, this means that the `read` function will return one of the
 /// following:
 ///
-/// * `Ok(n)` means that `n` bytes of data was immediately read and placed into
+/// * `Ok(Async::Ready(n))` means that `n` bytes of data was immediately read
-///   the output buffer, where `n` == 0 implies that EOF has been reached.
+///   and placed into the output buffer, where `n` == 0 implies that EOF has
+///   been reached.
 ///
-/// * `Err(e) if e.kind() == ErrorKind::WouldBlock` means that no data was read
+/// * `Ok(Async::NotReady)` means that no data was read into the buffer 
-///   into the buffer provided. The I/O object is not currently readable but may
+///   provided. The I/O object is not currently readable but may become readable
-///   become readable in the future. Most importantly, **the current future's
+///   in the future. Most importantly, **the current future's task is scheduled
-///   task is scheduled to get unparked when the object is readable**. This
+///   to get unparked when the object is readable**. This means that like 
-///   means that like `Future::poll` you'll receive a notification when the I/O
+///   `Future::poll` you'll receive a notification when the I/O object is 
-///   object is readable again.
+///   readable again.
 ///
 /// * `Err(e)` for other errors are standard I/O errors coming from the
 ///   underlying object.

tokio-io/src/async_write.rs

@@ -13,14 +13,15 @@ use AsyncRead;
 /// Specifically, this means that the `write` function will return one of the
 /// following:
 ///
-/// * `Ok(n)` means that `n` bytes of data was immediately written .
+/// * `Ok(Async::Ready(n))` means that `n` bytes of data was immediately
+///   written.
 ///
-/// * `Err(e) if e.kind() == ErrorKind::WouldBlock` means that no data was
+/// * `Ok(Async::NotReady)` means that no data was written from the buffer
-///   written from the buffer provided. The I/O object is not currently
+///   provided. The I/O object is not currently writable but may become writable
-///   writable but may become writable in the future. Most importantly, **the
+///   in the future. Most importantly, **the current future's task is scheduled
-///   current future's task is scheduled to get unparked when the object is
+///   to get unparked when the object is readable**. This means that like
-///   readable**. This means that like `Future::poll` you'll receive a
+///   `Future::poll` you'll receive a notification when the I/O object is
-///   notification when the I/O object is writable again.
+///   writable again.
 ///
 /// * `Err(e)` for other errors are standard I/O errors coming from the
 ///   underlying object.