Doc improvements (#46)

* small doc cleanups in PollEvented

* small doc cleanups in IoToken

* improve crate level documentation

- Add links to the futures, mio and tokio-uds crates.
- Add links to various structs and types mentioned.
- use eprintln for error reporting in the example.

* improvements to the UdpSocket documentation

- Fixed links usage.
- Removed references to a no longer existing `Window` struct.
- Made notes about using functions in context of a future.

* documentation improvements to UdpFramed and UdpCodec

- Since HTTP uses TCP (QUIC aside) using it as an example in an UDP
protocol feels wrong.
- Make the note of tampering with the underlying streams more explicit.

* update reactor module level documentation

Adds an explanation of every public struct.

* expand Handle and Remote documentation

* expand net module documentation

Adds an explanation of every public struct and how they work together.

* update TcpListener documentation

Reorder the various option methods; get first then set.
Note about panicing added to poll_read.

* remove mention of none-existing future R

* improve documentation of TcpStream

* fix UdpSocket doc

This when wrong when merging various commits.

src/reactor/poll_evented.rs

@@ -80,9 +80,6 @@ impl<E: fmt::Debug> fmt::Debug for PollEvented<E> {
 impl<E: Evented> PollEvented<E> {
     /// Creates a new readiness stream associated with the provided
     /// `loop_handle` and for the given `source`.
-    ///
-    /// This method returns a future which will resolve to the readiness stream
-    /// when it's ready.
     pub fn new(io: E, handle: &Handle) -> io::Result<PollEvented<E>> {
         let token = IoToken::new(&io, handle)?;
 
@@ -118,11 +115,11 @@ impl<E: Evented> PollEvented<E> {
 impl<E> PollEvented<E> {
     /// Tests to see if this source is ready to be read from or not.
     ///
-    /// If this stream is not ready for a read then `NotReady` will be returned
-    /// and the current task will be scheduled to receive a notification when
-    /// the stream is readable again. In other words, this method is only safe
-    /// to call from within the context of a future's task, typically done in a
-    /// `Future::poll` method.
+    /// If this stream is not ready for a read then `Async::NotReady` will be
+    /// returned and the current task will be scheduled to receive a
+    /// notification when the stream is readable again. In other words, this
+    /// method is only safe to call from within the context of a future's task,
+    /// typically done in a `Future::poll` method.
     ///
     /// This is mostly equivalent to `self.poll_ready(Ready::readable())`.
     ///
@@ -137,7 +134,7 @@ impl<E> PollEvented<E> {
 
     /// Tests to see if this source is ready to be written to or not.
     ///
-    /// If this stream is not ready for a write then `NotReady` will be returned
+    /// If this stream is not ready for a write then `Async::NotReady` will be returned
     /// and the current task will be scheduled to receive a notification when
     /// the stream is writable again. In other words, this method is only safe
     /// to call from within the context of a future's task, typically done in a