Add `io` facade and update `reactor` docs (#166)

This patch updates the documentation for a number of APIs. It also
introduces a prelude module and an io facade module, re-exporting types
from tokio-io.

2 files changed, 18 insertions, 14 deletions

diff --git a/tokio-io/src/async_read.rs b/tokio-io/src/async_read.rs
index fb72c14b..08d851ef 100644
--- a/tokio-io/src/async_read.rs
+++ b/tokio-io/src/async_read.rs
@@ -6,23 +6,25 @@ use {framed, split, AsyncWrite};
 use codec::{Decoder, Encoder, Framed};
 use split::{ReadHalf, WriteHalf};
 
-/// A trait for readable objects which operated in an asynchronous and
-/// futures-aware fashion.
+/// Read bytes asynchronously.
 ///
-/// This trait inherits from `io::Read` and indicates as a marker that an I/O
-/// object is **nonblocking**, meaning that it will return an error instead of
-/// blocking when bytes are unavailable, but the stream hasn't reached EOF.
-/// Specifically this means that the `read` function for types that implement
-/// this trait can have a few return values:
+/// This trait inherits from `std::io::Read` and indicates that an I/O object is
+/// **non-blocking**. All non-blocking I/O objects must return an error when
+/// bytes are unavailable instead of blocking the current thread.
+///
+/// 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
 ///   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
 ///   into the buffer provided. The I/O object is not currently readable but may
 ///   become readable in the future. Most importantly, **the current future's
 ///   task is scheduled to get unparked when the object is readable**. This
 ///   means that like `Future::poll` you'll receive a notification when the I/O
 ///   object is readable again.
+///
 /// * `Err(e)` for other errors are standard I/O errors coming from the
 ///   underlying object.
 ///
diff --git a/tokio-io/src/async_write.rs b/tokio-io/src/async_write.rs
index e152cd5a..8c27ee12 100644
--- a/tokio-io/src/async_write.rs
+++ b/tokio-io/src/async_write.rs
@@ -5,22 +5,24 @@ use futures::{Async, Poll};
 
 use AsyncRead;
 
-/// A trait for writable objects which operated in an asynchronous and
-/// futures-aware fashion.
+/// Writes bytes asynchronously.
 ///
-/// This trait inherits from `io::Write` and indicates that an I/O object is
-/// **nonblocking**, meaning that it will return an error instead of blocking
-/// when bytes cannot currently be written, but hasn't closed. Specifically
-/// this means that the `write` function for types that implement this trait
-/// can have a few return values:
+/// The trait inherits from `std::io::Write` and indicates that an I/O object is
+/// **nonblocking**. All non-blocking I/O objects must return an error when
+/// bytes cannot be written instead of blocking the current thread.
+///
+/// Specifically, this means that the `write` function will return one of the
+/// following:
 ///
 /// * `Ok(n)` means that `n` bytes of data was immediately written .
+///
 /// * `Err(e) if e.kind() == ErrorKind::WouldBlock` means that no data was
 ///   written from the buffer provided. The I/O object is not currently
 ///   writable but may become writable in the future. Most importantly, **the
 ///   current future's task is scheduled to get unparked when the object is
 ///   readable**. This means that like `Future::poll` you'll receive a
 ///   notification when the I/O object is writable again.
+///
 /// * `Err(e)` for other errors are standard I/O errors coming from the
 ///   underlying object.
 ///