Various improvements

.travis.yml

@@ -1,30 +1,26 @@
----
-language: rust
 sudo: false
-
+cache: cargo
+os:
+  - linux
+  - osx
+language: rust
 rust:
   - stable
   - beta
   - nightly
-
 before_script:
   - pip install 'travis-cargo<0.2' --user && export PATH=$HOME/.local/bin:$PATH
-
 script:
-  - cargo build
-  - cargo test
+  - cargo --version
+  - rustc --version
+  - cargo build --verbose
+  - cargo test --verbose
   - cargo doc --no-deps
-
 after_success:
   - travis-cargo --only nightly doc-upload --branch new-crate
-
 env:
   global:
     - secure: iwlN1zfUCp/5BAAheqIRSFIqiM9zSwfIGcVDw/V7jHveqXyNzmCs7H58/cd90WLqonqpPX0t5GF66oTjms4v0DFjgXr/k4358qeSZaV082V3baNrVpCDHeCQV0SvKsfiYxDDJGSUL1WIUP+tqqDm4+ksZQP3LnwZojkABjWz5CBNt4kX+Wz5ZbYqtQoxyuZba5UyPY2CXJtubvCVPGMJULuUpklYxXZ4dWM2olzGgVJ8rE8udhSZ4ER4JgxB0KUx3/5TwHHzgyPEsWR4bKN6JzBjIczQofXUcUXXdoZBs23H/VhCpzKcn3/oJ8btVYPzwtdj5FmVB1aVR/gjPo2bSGi/sofq+LwL/1HJXkM+kjl8m2dLLcDBKqNYNERtVA1++LhkMWAFRgGYe8v8Ryxjiue1NF5LgAIA/fjK0uI1DELTzTf/TKrM+AtPDNTvhOft4/YD+hoImjwk6nv6PBb2TiTYnc79Qf4AZ65tv1qtsAUPuw4plLaccHQAO4ldYVXn4u9c+iisJwvovs6jo06bF3U3qtdI5gXsrI9+T25TrXvYb+IREo0MHzYEM0KlPFnscEArzC3eajuSd36ARFP3lDc+gp2RPs89iJjowms0eRyepp7Cu6XO3Cd2pfAX8AqvnmttZf4Nm51ONeiBPXPXItUkJm49MCpMJywU1IZcWZg=
-
 notifications:
   email:
     on_success: never
-
-os:
-  - linux

Cargo.toml

@@ -10,7 +10,7 @@ description = """
 Core I/O and event loop primitives for asynchronous I/O in Rust. Foundation for
 the rest of the tokio crates.
 """
-categories = ["asynchronous"]
+categories = ["asynchronous", "I/O", "none-blocking"]
 
 [badges]
 travis-ci = { repository = "tokio-rs/tokio" }

examples/echo-udp.rs

@@ -11,7 +11,6 @@
 //! Each line you type in to the `nc` terminal should be echo'd back to you!
 
 extern crate futures;
-#[macro_use]
 extern crate tokio;
 #[macro_use]
 extern crate tokio_io;

src/lib.rs

@@ -1,21 +1,28 @@
 //! `Future`-powered I/O at the core of Tokio
 //!
-//! This crate uses the `futures` crate to provide an event loop ("reactor
+//! This crate uses the [`futures`] crate to provide an event loop ("reactor
 //! core") which can be used to drive I/O like TCP and UDP. All asynchronous I/O
-//! is powered by the `mio` crate.
+//! is powered by the [`mio`] crate.
+//!
+//! [`futures`]: ../futures/index.html
+//! [`mio`]: ../mio/index.html
 //!
 //! The concrete types provided in this crate are relatively bare bones but are
 //! intended to be the essential foundation for further projects needing an
 //! event loop. In this crate you'll find:
 //!
-//! * TCP, both streams and listeners
-//! * UDP sockets
-//! * An event loop to run futures
+//! * TCP, both streams and listeners.
+//! * UDP sockets.
+//! * An event loop to run futures.
 //!
 //! More functionality is likely to be added over time, but otherwise the crate
-//! is intended to be flexible, with the `PollEvented` type accepting any
-//! type that implements `mio::Evented`. For example, the `tokio-uds` crate
-//! uses `PollEvented` to provide support for Unix domain sockets.
+//! is intended to be flexible, with the [`PollEvented`] type accepting any
+//! type that implements [`mio::Evented`]. For example, the [`tokio-uds`] crate
+//! uses [`PollEvented`] to provide support for Unix domain sockets.
+//!
+//! [`PollEvented`]: ./reactor/struct.PollEvented.html
+//! [`mio::Evented`]: ../mio/event/trait.Evented.html
+//! [`tokio-uds`]: https://crates.io/crates/tokio-uds
 //!
 //! Some other important tasks covered by this crate are:
 //!
@@ -45,60 +52,60 @@
 //! use tokio::reactor::Core;
 //!
 //! fn main() {
-//!     // Create the event loop that will drive this server
+//!     // Create the event loop that will drive this server.
 //!     let mut core = Core::new().unwrap();
 //!     let handle = core.handle();
 //!
 //!     let pool = CpuPool::new_num_cpus();
 //!
-//!     // Bind the server's socket
+//!     // Bind the server's socket.
 //!     let addr = "127.0.0.1:12345".parse().unwrap();
-//!     let listener = TcpListener::bind(&addr, &handle).unwrap();
+//!     let listener = TcpListener::bind(&addr, &handle)
+//!         .expect("unable to bind TCP listener");
 //!
 //!     // Pull out a stream of sockets for incoming connections
 //!     let server = listener.incoming().for_each(|(sock, _)| {
 //!         // Split up the reading and writing parts of the
-//!         // socket
+//!         // socket.
 //!         let (reader, writer) = sock.split();
 //!
 //!         // A future that echos the data and returns how
 //!         // many bytes were copied...
 //!         let bytes_copied = copy(reader, writer);
 //!
-//!         // ... after which we'll print what happened
+//!         // ... after which we'll print what happened.
 //!         let handle_conn = bytes_copied.map(|amt| {
 //!             println!("wrote {:?} bytes", amt)
 //!         }).map_err(|err| {
-//!             println!("IO error {:?}", err)
+//!             eprintln!("IO error {:?}", err)
 //!         });
 //!
-//!         // Spawn the future as a concurrent task
+//!         // Spawn the future as a concurrent task.
 //!         pool.execute(handle_conn).unwrap();
 //!
 //!         Ok(())
 //!     });
 //!
-//!     // Spin up the server on the event loop
+//!     // Spin up the server on the event loop.
 //!     core.run(server).unwrap();
 //! }
 //! ```
 
 #![doc(html_root_url = "https://docs.rs/tokio-core/0.1")]
 #![deny(missing_docs)]
+#![warn(missing_debug_implementations)]
 #![deny(warnings)]
-#![allow(unused_macros)]
 
 extern crate bytes;
 #[macro_use]
 extern crate futures;
 extern crate iovec;
+#[macro_use]
+extern crate log;
 extern crate mio;
 extern crate slab;
 #[macro_use]
 extern crate tokio_io;
 
-#[macro_use]
-extern crate log;
-
 pub mod net;
 pub mod reactor;

src/net/mod.rs

@@ -1,11 +1,46 @@
-//! TCP/UDP bindings for `tokio-core`
+//! TCP/UDP bindings for `tokio`.
 //!
 //! This module contains the TCP/UDP networking types, similar to the standard
 //! library, which can be used to implement networking protocols.
+//!
+//! # TCP
+//!
+//! Connecting to an address, via TCP, can be done using [`TcpStream`]'s
+//! [`connect`] method, which returns [`TcpStreamNew`]. `TcpStreamNew`
+//! implements a future which returns a `TcpStream`.
+//!
+//! To listen on an address [`TcpListener`] can be used. `TcpListener`'s
+//! [`incoming`][incoming_method] method can be used to accept new connections.
+//! It return the [`Incoming`] struct, which implements a stream which returns
+//! `TcpStream`s.
+//!
+//! [`TcpStream`]: struct.TcpStream.html
+//! [`connect`]: struct.TcpStream.html#method.connect
+//! [`TcpStreamNew`]: struct.TcpStreamNew.html
+//! [`TcpListener`]: struct.TcpListener.html
+//! [incoming_method]: struct.TcpListener.html#method.incoming
+//! [`Incoming`]: struct.Incoming.html
+//!
+//! # UDP
+//!
+//! The main struct for UDP is the [`UdpSocket`], which represents a UDP socket.
+//! Reading and writing to it can be done using futures, which return the
+//! [`RecvDgram`] and [`SendDgram`] structs respectively.
+//!
+//! For convience it's also possible to convert raw datagrams into higher-level
+//! frames. This done with [`UdpFramed`], created by calling [`framed`] on a
+//! [`UdpSocket`], and using the [`UdpCodec`].
+//!
+//! [`UdpSocket`]: struct.UdpSocket.html
+//! [`RecvDgram`]: struct.RecvDgram.html
+//! [`SendDgram`]: struct.SendDgram.html
+//! [`UdpFramed`]: struct.UdpFramed.html
+//! [`framed`]: struct.UdpSocket.html#method.framed
+//! [`UdpCodec`]: trait.UdpCodec.html
 
 mod tcp;
 mod udp;
 
 pub use self::tcp::{TcpStream, TcpStreamNew};
-pub use self::tcp::{TcpListener, Incoming};
-pub use self::udp::{UdpSocket, UdpCodec, UdpFramed, SendDgram, RecvDgram};
+pub use self::tcp::{Incoming, TcpListener};
+pub use self::udp::{RecvDgram, SendDgram, UdpCodec, UdpFramed, UdpSocket};