General rustdoc improvements (#450)

* Normalize links to docs.rs/CRATE/M.N/...

docs.rs is smart enough to show docs for the latest M.N.P release when
M.N is used in the link. For example:

  https://docs.rs/mio/0.6/mio/struct.Poll.html

..will show mio 0.6.14 and later docs. While using the `M.N.*`
(ASTERISK) syntax also works, `M.N` is the more common usage, so
standarize a few existing links to that format.

* Fix missing or malformed rustdoc links

* executor lib rustdoc minor format change

* Promote tokio-threadpool crate level comments to rustdoc

* Replace hidden tokio::executor::thread_pool docs with deprecation note

* Fix typo/simplify util module rustdoc

* Reuse some tokio::executor::thread_pool rustdoc for the crate

Relates to #421

tokio-executor/src/lib.rs

@@ -7,8 +7,9 @@
 //!
 //! 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.
+//! 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;