General rustdoc improvements

README.md

@@ -53,7 +53,7 @@ These components provide the runtime components necessary for building
 an asynchronous application.
 
 [net]: https://docs.rs/tokio/0.1/tokio/net/index.html
-[reactor]: https://docs.rs/tokio/0.1.1/tokio/reactor/index.html
+[reactor]: https://docs.rs/tokio/0.1/tokio/reactor/index.html
 [scheduler]: https://tokio-rs.github.io/tokio/tokio/runtime/index.html
 
 ## Example

src/executor/mod.rs

@@ -44,79 +44,10 @@
 pub mod current_thread;
 
 #[deprecated(since = "0.1.8", note = "use tokio-threadpool crate instead")]
-#[doc(hidden)]
+/// Re-exports of [`tokio-threadpool`], deprecated in favor of the crate.
+///
+/// [`tokio-threadpool`]: https://docs.rs/tokio-threadpool/0.1
 pub mod thread_pool {
- //! Maintains a pool of threads across which the set of spawned tasks are
- //! executed.
- //!
- //! [`ThreadPool`] is an executor that uses a thread pool for executing
- //! tasks concurrently across multiple cores. It uses a thread pool that is
- //! optimized for use cases that involve multiplexing large number of
- //! independent tasks that perform short(ish) amounts of computation and are
- //! mainly waiting on I/O, i.e. the Tokio use case.
- //!
- //! Usually, users of [`ThreadPool`] will not create pool instances.
- //! Instead, they will create a [`Runtime`] instance, which comes with a
- //! pre-configured thread pool.
- //!
- //! At the core, [`ThreadPool`] uses a work-stealing based scheduling
- //! strategy. When spawning a task while *external* to the thread pool
- //! (i.e., from a thread that is not part of the thread pool), the task is
- //! randomly assigned to a worker thread. When spawning a task while
- //! *internal* to the thread pool, the task is assigned to the current
- //! worker.
- //!
- //! Each worker maintains its own queue and first focuses on processing all
- //! tasks in its queue. When the worker's queue is empty, the worker will
- //! attempt to *steal* tasks from other worker queues. This strategy helps
- //! ensure that work is evenly distributed across threads while minimizing
- //! synchronization between worker threads.
- //!
- //! # Usage
- //!
- //! Thread pool instances are created using [`ThreadPool::new`] or
- //! [`Builder::new`]. The first option returns a thread pool with default
- //! configuration values. The second option allows configuring the thread
- //! pool before instantiating it.
- //!
- //! Once an instance is obtained, futures may be spawned onto it using the
- //! [`spawn`] function.
- //!
- //! A handle to the thread pool is obtained using [`ThreadPool::sender`].
- //! This handle is **only** able to spawn futures onto the thread pool. It
- //! is unable to affect the lifecycle of the thread pool in any way. This
- //! handle can be passed into functions or stored in structs as a way to
- //! grant the capability of spawning futures.
- //!
- //! # Examples
- //!
- //! ```rust
- //! # extern crate tokio;
- //! # extern crate futures;
- //! # use tokio::executor::thread_pool::ThreadPool;
- //! use futures::future::{Future, lazy};
- //!
- //! # pub fn main() {
- //! // Create a thread pool with default configuration values
- //! let thread_pool = ThreadPool::new();
- //!
- //! thread_pool.spawn(lazy(|| {
- //! println!("called from a worker thread");
- //! Ok(())
- //! }));
- //!
- //! // Gracefully shutdown the threadpool
- //! thread_pool.shutdown().wait().unwrap();
- //! # }
- //! ```
- //!
- //! [`ThreadPool`]: struct.ThreadPool.html
- //! [`ThreadPool::new`]: struct.ThreadPool.html#method.new
- //! [`ThreadPool::sender`]: struct.ThreadPool.html#method.sender
- //! [`spawn`]: struct.ThreadPool.html#method.spawn
- //! [`Builder::new`]: struct.Builder.html#method.new
- //! [`Runtime`]: ../../runtime/struct.Runtime.html
-
  pub use tokio_threadpool::{
  Builder,
  Sender,

src/lib.rs

@@ -5,7 +5,7 @@
 //! provides a few major components:
 //!
 //! * A multi threaded, work-stealing based task [scheduler][runtime].
-//! * A [reactor][reactor] backed by the operating system's event queue (epoll, kqueue,
+//! * A [reactor] backed by the operating system's event queue (epoll, kqueue,
 //! IOCP, etc...).
 //! * Asynchronous [TCP and UDP][net] sockets.
 //! * Asynchronous [filesystem][fs] operations.
@@ -17,7 +17,7 @@
 //! Guide level documentation is found on the [website].
 //!
 //! [website]: https://tokio.rs/docs/getting-started/hello-world/
-//! [futures]: http://docs.rs/futures
+//! [futures]: http://docs.rs/futures/0.1
 //!
 //! # Examples
 //!

src/runtime/current_thread/mod.rs

@@ -62,6 +62,9 @@
 //! [rt]: struct.Runtime.html
 //! [concurrent-rt]: ../struct.Runtime.html
 //! [chan]: https://docs.rs/futures/0.1/futures/sync/mpsc/fn.channel.html
+//! [reactor]: ../../reactor/struct.Reactor.html
+//! [executor]: https://tokio.rs/docs/getting-started/runtime-model/#executors
+//! [timer]: ../../timer/index.html
 
 mod builder;
 mod runtime;

src/timer.rs

@@ -76,6 +76,9 @@
 //! [runtime]: ../runtime/struct.Runtime.html
 //! [tokio-timer]: https://docs.rs/tokio-timer
 //! [ext]: ../util/trait.FutureExt.html#method.deadline
+//! [Deadline]: struct.Deadline.html
+//! [Delay]: struct.Delay.html
+//! [Interval]: struct.Interval.html
 
 pub use tokio_timer::{
  Deadline,

src/util/mod.rs

@@ -1,8 +1,9 @@
 //! Utilities for working with Tokio.
 //!
 //! This module contains utilities that are useful for working with Tokio.
-//! Currently, this only includes [`FutureExt`][FutureExt]. However, this will
-//! include over time.
+//! Currently, this only includes [`FutureExt`], but this may grow over time.
+//!
+//! [`FutureExt`]: trait.FutureExt.html
 
 mod future;
 

tokio-executor/src/lib.rs

@@ -6,9 +6,10 @@
 //! an executor is called a "task".
 //!
 //! The executor is responsible for ensuring that [`Future::poll`] is called
-//! whenever the task is [notified]. Notification happens when the internal
-//! state of a task transitions from "not ready" to ready. For example, a socket
-//! might have received data and a call to `read` will now be able to succeed.
+//! whenever the task is notified. Notification happens when the internal
+//! state of a task transitions from *not ready* to *ready*. For example, a
+//! socket might have received data and a call to `read` will now be able to
+//! succeed.
 //!
 //! This crate provides traits and utilities that are necessary for building an
 //! executor, including:
@@ -29,6 +30,7 @@
 //! [`enter`]: fn.enter.html
 //! [`DefaultExecutor`]: struct.DefaultExecutor.html
 //! [`Park`]: park/index.html
+//! [`Future::poll`]: https://docs.rs/futures/0.1/futures/future/trait.Future.html#tymethod.poll
 
 #![deny(missing_docs, missing_debug_implementations, warnings)]
 #![doc(html_root_url = "https://docs.rs/tokio-executor/0.1.2")]

tokio-executor/src/park.rs

@@ -42,7 +42,7 @@
 //! [`park_timeout`]: trait.Park.html#tymethod.park_timeout
 //! [`unpark`]: trait.Unpark.html#tymethod.unpark
 //! [up]: trait.Unpark.html
-//! [mio]: https://docs.rs/mio/0.6.13/mio/struct.Poll.html
+//! [mio]: https://docs.rs/mio/0.6/mio/struct.Poll.html
 
 use std::marker::PhantomData;
 use std::rc::Rc;

tokio-fs/src/file/mod.rs

@@ -190,7 +190,9 @@ impl File {
  ///
  /// # Panics
  ///
- /// This function will panic if [`shutdown`] has been called.
+ /// This function will panic if `shutdown` has been called.
+ ///
+ /// [std]: https://doc.rust-lang.org/std/fs/struct.File.html
  pub fn into_std(mut self) -> StdFile {
  self.std.take().expect("`File` instance already shutdown")
  }

tokio-io/src/codec/mod.rs

@@ -104,7 +104,7 @@ pub mod length_delimited {
  //! [`FramedRead`] adapts an [`AsyncRead`] into a `Stream` of [`BytesMut`],
  //! such that each yielded [`BytesMut`] value contains the contents of an
  //! entire frame. There are many configuration parameters enabling
- //! [`FrameRead`] to handle a wide range of protocols. Here are some
+ //! [`FramedRead`] to handle a wide range of protocols. Here are some
  //! examples that will cover the various options at a high level.
  //!
  //! ## Example 1
@@ -370,7 +370,7 @@ pub mod length_delimited {
  //! [`AsyncRead`]: ../../trait.AsyncRead.html
  //! [`AsyncWrite`]: ../../trait.AsyncWrite.html
  //! [`Encoder`]: ../trait.Encoder.html
- //! [`BytesMut`]: https://docs.rs/bytes/~0.4/bytes/struct.BytesMut.html
+ //! [`BytesMut`]: https://docs.rs/bytes/0.4/bytes/struct.BytesMut.html
 
  pub use ::length_delimited::*;
 }