docs: fix all rustdoc warnings (#1474)

azure-pipelines.yml

@@ -115,16 +115,18 @@ jobs:
 #   parameters:
 #     name: tsan
 #     rust: $(nightly)
-#
+
-# - template: ci/azure-deploy-docs.yml
+- template: ci/azure-deploy-docs.yml
-#   parameters:
+  parameters:
-#     dependsOn:
+    rust: $(nightly)
-#       - rustfmt
+    dependsOn:
-#       - test_tokio
+      - rustfmt
-#       - test_sub_cross
+      - clippy
-#       - test_linux
+      - test_tokio
-#       - features
+      - test_sub_cross
-#       - test_nightly
+      - test_linux
-#       - cross_32bit_linux
+      - test_features
-#       - minrust
+#      - test_nightly
-#       - tsan
+#      - cross_32bit_linux
+#      - minrust
+#      - tsan

ci/azure-deploy-docs.yml

@@ -12,9 +12,10 @@ jobs:
   steps:
   - template: azure-install-rust.yml
     parameters:
-      rust_version: stable
+      # rust_version: stable
+      rust_version: ${{ parameters.rust }}
   - script: |
-      cargo doc --all --no-deps
+      cargo doc --all --no-deps --all-features
       cp -R target/doc '$(Build.BinariesDirectory)'
     displayName: 'Generate Documentation'
   - script: |

tokio-executor/src/typed.rs

@@ -20,6 +20,7 @@ use crate::SpawnError;
 /// such, the function takes a stream and an executor on which the background
 /// task is spawned.
 ///
+/// [`spawn`]: TypedExecutor::spawn
 /// ```
 /// #![feature(async_await)]
 ///

tokio-io/src/async_read.rs

@@ -59,7 +59,7 @@ pub trait AsyncRead {
     ///
     /// This function is called from [`poll_read_buf`].
     ///
-    /// [`io::Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
+    /// [`io::Read`]: std::io::Read
     /// [`poll_read_buf`]: #method.poll_read_buf
     unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool {
         for x in buf {

tokio-io/src/io/buf_reader.rs

@@ -22,9 +22,6 @@ use std::{cmp, fmt};
 /// When the `BufReader` is dropped, the contents of its buffer will be
 /// discarded. Creating multiple instances of a `BufReader` on the same
 /// stream can cause data loss.
-///
-/// [`AsyncRead`]: tokio_io::AsyncRead
-///
 // TODO: Examples
 pub struct BufReader<R> {
     inner: R,

tokio-io/src/io/buf_writer.rs

@@ -24,7 +24,7 @@ use std::task::{Context, Poll};
 /// stream can cause data loss. If you need to write out the contents of its
 /// buffer, you must manually call flush before the writer is dropped.
 ///
-/// [`AsyncWrite`]: tokio_io::AsyncWrite
+/// [`AsyncWrite`]: AsyncWrite
 /// [`flush`]: super::AsyncWriteExt::flush
 ///
 // TODO: Examples

tokio-io/src/io/flush.rs

@@ -7,8 +7,6 @@ use std::task::{Context, Poll};
 /// A future used to fully flush an I/O object.
 ///
 /// Created by the [`AsyncWriteExt::flush`] function.
-///
-/// [`flush`]: fn.flush.html
 #[derive(Debug)]
 pub struct Flush<'a, A: ?Sized> {
     a: &'a mut A,

tokio-io/src/io/mod.rs

@@ -1,41 +1,3 @@
-//! Asynchronous I/O.
-//!
-//! This module is the asynchronous version of `std::io`. Primarily, it
-//! defines two traits, [`AsyncRead`] and [`AsyncWrite`], which extend the
-//! `Read` and `Write` traits of the standard library.
-//!
-//! # AsyncRead and AsyncWrite
-//!
-//! [`AsyncRead`] and [`AsyncWrite`] must only be implemented for
-//! non-blocking I/O types that integrate with the futures type system. In
-//! other words, these types must never block the thread, and instead the
-//! current task is notified when the I/O resource is ready.
-//!
-//! # Standard input and output
-//!
-//! Tokio provides asynchronous APIs to standard [input], [output], and [error].
-//! These APIs are very similar to the ones provided by `std`, but they also
-//! implement [`AsyncRead`] and [`AsyncWrite`].
-//!
-//! Unlike *most* other Tokio APIs, the standard input / output APIs
-//! **must** be used from the context of the Tokio runtime as they require
-//! Tokio specific features to function.
-//!
-//! [input]: fn.stdin.html
-//! [output]: fn.stdout.html
-//! [error]: fn.stderr.html
-//!
-//! # `std` re-exports
-//!
-//! Additionally, [`Error`], [`ErrorKind`], and [`Result`] are re-exported
-//! from `std::io` for ease of use.
-//!
-//! [`AsyncRead`]: trait.AsyncRead.html
-//! [`AsyncWrite`]: trait.AsyncWrite.html
-//! [`Error`]: struct.Error.html
-//! [`ErrorKind`]: enum.ErrorKind.html
-//! [`Result`]: type.Result.html
-
 mod async_buf_read_ext;
 mod async_read_ext;
 mod async_write_ext;

tokio-io/src/io/read_exact.rs

@@ -9,9 +9,7 @@ use std::task::{Context, Poll};
 /// A future which can be used to easily read exactly enough bytes to fill
 /// a buffer.
 ///
-/// Created by the [`read_exact`] function.
+/// Created by the [`AsyncRead::read_exact`].
-///
-/// [`read_exact`]: fn.read_exact.html
 pub(crate) fn read_exact<'a, A>(reader: &'a mut A, buf: &'a mut [u8]) -> ReadExact<'a, A>
 where
     A: AsyncRead + Unpin + ?Sized,

tokio-io/src/io/shutdown.rs

@@ -7,8 +7,6 @@ use std::task::{Context, Poll};
 /// A future used to shutdown an I/O object.
 ///
 /// Created by the [`AsyncWriteExt::shutdown`] function.
-///
-/// [`shutdown`]: fn.shutdown.html
 #[derive(Debug)]
 pub struct Shutdown<'a, A: ?Sized> {
     a: &'a mut A,

tokio-net/src/tcp/listener.rs

@@ -262,8 +262,10 @@ impl TryFrom<TcpListener> for mio::net::TcpListener {
 
     /// Consumes value, returning the mio I/O object.
     ///
-    /// See [`tokio_net::util::PollEvented::into_inner`] for more details about
+    /// See [`PollEvented::into_inner`] for more details about
     /// resource deregistration that happens during the call.
+    ///
+    /// [`PollEvented::into_inner`]: crate::util::PollEvented::into_inner
     fn try_from(value: TcpListener) -> Result<Self, Self::Error> {
         value.io.into_inner()
     }

tokio-net/src/tcp/stream.rs

@@ -802,8 +802,10 @@ impl TryFrom<TcpStream> for mio::net::TcpStream {
 
     /// Consumes value, returning the mio I/O object.
     ///
-    /// See [`tokio_net::util::PollEvented::into_inner`] for more details about
+    /// See [`PollEvented::into_inner`] for more details about
     /// resource deregistration that happens during the call.
+    ///
+    /// [`PollEvented::into_inner`]: crate::util::PollEvented::into_inner
     fn try_from(value: TcpStream) -> Result<Self, Self::Error> {
         value.io.into_inner()
     }

tokio-net/src/udp/mod.rs

@@ -4,8 +4,8 @@
 //! library, which can be used to implement networking protocols.
 //!
 //! 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
+//!
-//! [`Recv`], [`Send`], [`RecvFrom`] and [`SendTo`] structs respectively.
+//! [`UdpSocket`]: struct.UdpSocket
 
 mod frame;
 mod socket;

tokio-net/src/udp/socket.rs

@@ -328,8 +328,10 @@ impl TryFrom<UdpSocket> for mio::net::UdpSocket {
 
     /// Consumes value, returning the mio I/O object.
     ///
-    /// See [`tokio_net::util::PollEvented::into_inner`] for more details about
+    /// See [`PollEvented::into_inner`] for more details about
     /// resource deregistration that happens during the call.
+    ///
+    /// [`PollEvented::into_inner`]: crate::util::PollEvented::into_inner
     fn try_from(value: UdpSocket) -> Result<Self, Self::Error> {
         value.io.into_inner()
     }

tokio-net/src/uds/datagram.rs

@@ -201,8 +201,10 @@ impl TryFrom<UnixDatagram> for mio_uds::UnixDatagram {
 
     /// Consumes value, returning the mio I/O object.
     ///
-    /// See [`tokio_net::util::PollEvented::into_inner`] for more details about
+    /// See [`PollEvented::into_inner`] for more details about
     /// resource deregistration that happens during the call.
+    ///
+    /// [`PollEvented::into_inner`]: crate::util::PollEvented::into_inner
     fn try_from(value: UnixDatagram) -> Result<Self, Self::Error> {
         value.io.into_inner()
     }

tokio-net/src/uds/listener.rs

@@ -102,8 +102,10 @@ impl TryFrom<UnixListener> for mio_uds::UnixListener {
 
     /// Consumes value, returning the mio I/O object.
     ///
-    /// See [`tokio_net::util::PollEvented::into_inner`] for more details about
+    /// See [`PollEvented::into_inner`] for more details about
     /// resource deregistration that happens during the call.
+    ///
+    /// [`PollEvented::into_inner`]: crate::util::PollEvented::into_inner
     fn try_from(value: UnixListener) -> Result<Self, Self::Error> {
         value.io.into_inner()
     }

tokio-net/src/uds/stream.rs

@@ -131,8 +131,10 @@ impl TryFrom<UnixStream> for mio_uds::UnixStream {
 
     /// Consumes value, returning the mio I/O object.
     ///
-    /// See [`tokio_net::util::PollEvented::into_inner`] for more details about
+    /// See [`PollEvented::into_inner`] for more details about
     /// resource deregistration that happens during the call.
+    ///
+    /// [`PollEvented::into_inner`]: crate::util::PollEvented::into_inner
     fn try_from(value: UnixStream) -> Result<Self, Self::Error> {
         value.io.into_inner()
     }

tokio-test/src/io.rs

@@ -12,6 +12,9 @@
 //!
 //! Attempting to write data that the mock isn't expected will result in a
 //! panic.
+//!
+//! [`AsyncRead`]: tokio_io::AsyncRead
+//! [`AsyncWrite`]: tokio_io::AsyncWrite
 
 use std::collections::VecDeque;
 use std::future::Future;

tokio-timer/src/clock/mod.rs

@@ -12,8 +12,8 @@
 //!
 //! [n]: fn.now.html
 //! [`Now`]: trait.Now.html
-//! [`Instant`]: https://doc.rust-lang.org/std/time/struct.Instant.html
+//! [`Instant`]: std::time::Instant
-//! [`Instant::now`]: https://doc.rust-lang.org/std/time/struct.Instant.html#method.now
+//! [`Instant::now`]: std::time::Instant::now
 //! [`with_default`]: fn.with_default.html
 
 mod now;
@@ -31,8 +31,8 @@ use std::time::Instant;
 /// `Clock` instances return [`Instant`] values corresponding to "now". The source
 /// of these values is configurable. The default source is [`Instant::now`].
 ///
-/// [`Instant`]: https://doc.rust-lang.org/std/time/struct.Instant.html
+/// [`Instant`]: std::time::Instant
-/// [`Instant::now`]: https://doc.rust-lang.org/std/time/struct.Instant.html#method.now
+/// [`Instant::now`]: std::time::Instant::now
 #[derive(Default, Clone)]
 pub struct Clock {
     now: Option<Arc<dyn Now>>,
@@ -87,7 +87,7 @@ impl Clock {
     /// Return a new `Clock` instance that uses [`Instant::now`] as the source
     /// of time.
     ///
-    /// [`Instant::now`]: https://doc.rust-lang.org/std/time/struct.Instant.html#method.now
+    /// [`Instant::now`]: std::time::Instant::now
     pub fn system() -> Clock {
         Clock { now: None }
     }

tokio-timer/src/clock/now.rs

@@ -8,7 +8,7 @@ use std::time::Instant;
 /// Implementations must ensure that calls to `now` return monotonically
 /// increasing [`Instant`] values.
 ///
-/// [`Instant`]: https://doc.rust-lang.org/std/time/struct.Instant.html
+/// [`Instant`]: std::time::Instant
 pub trait Now: Send + Sync + 'static {
     /// Returns an instant corresponding to "now".
     fn now(&self) -> Instant;

tokio-timer/src/lib.rs

@@ -31,10 +31,10 @@
 //!
 //! [`Delay`]: struct.Delay.html
 //! [`DelayQueue`]: struct.DelayQueue.html
-//! [`Throttle`]: throttle/struct.Throttle.html
+//! [`Throttle`]: throttle::Throttle
 //! [`Timeout`]: struct.Timeout.html
 //! [`Interval`]: struct.Interval.html
-//! [`Timer`]: timer/struct.Timer.html
+//! [`Timer`]: timer::Timer
 
 pub mod clock;
 pub mod delay_queue;

tokio-timer/src/timer/handle.rs

@@ -108,7 +108,7 @@ impl Handle {
     ///
     /// See [type] level documentation for more ways to obtain a `Handle` value.
     ///
-    /// [`with_default`]: ../fn.with_default.html
+    /// [`with_default`]: fn.with_default
     /// [type]: #
     pub fn current() -> Handle {
         let private =

tokio-timer/src/timer/mod.rs

@@ -23,12 +23,12 @@
 //!
 //! [`Timer`]: struct.Timer.html
 //! [`Handle`]: struct.Handle.html
-//! [`Delay`]: ../struct.Delay.html
+//! [`Delay`]: Delay
-//! [`Now`]: ../clock/trait.Now.html
+//! [`Now`]: clock::Now
-//! [`Now::now`]: ../clock/trait.Now.html#method.now
+//! [`Now::now`]: clock::Now::now
 //! [`SystemNow`]: struct.SystemNow.html
-//! [`Instant`]: https://doc.rust-lang.org/std/time/struct.Instant.html
+//! [`Instant`]: std::time::Instant
-//! [`Instant::now`]: https://doc.rust-lang.org/std/time/struct.Instant.html#method.now
+//! [`Instant::now`]: std::time::Instant::now
 
 // This allows the usage of the old `Now` trait.
 #![allow(deprecated)]
@@ -115,9 +115,9 @@ use tokio_executor::park::{Park, ParkThread, Unpark};
 /// either be canceled (dropped) or their associated entries will reach level
 /// zero and be notified.
 ///
-/// [`Delay`]: ../struct.Delay.html
+/// [`Delay`]: struct.Delay.html
-/// [`Interval`]: ../struct.Interval.html
+/// [`Interval`]: struct.Interval.html
-/// [`Timeout`]: ../struct.Timeout.html
+/// [`Timeout`]: struct.Timeout.html
 /// [paper]: http://www.cs.columbia.edu/~nahum/w6998/papers/ton97-timing-wheels.pdf
 /// [`handle`]: #method.handle
 /// [`turn`]: #method.turn

tokio/src/lib.rs

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

tokio/src/net.rs

@@ -50,14 +50,8 @@ pub mod udp {
     //! UDP bindings for `tokio`.
     //!
     //! 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
-    //! [`Recv`], [`Send`], [`RecvFrom`], [`SendTo`] structs respectively.
     //!
     //! [`UdpSocket`]: struct.UdpSocket.html
-    //! [`Recv`]: struct.Recv.html
-    //! [`Send`]: struct.Send.html
-    //! [`RecvFrom`]: struct.RecvFrom.html
-    //! [`SendTo`]: struct.SendTo.html
     pub use tokio_net::udp::{split, UdpFramed, UdpSocket};
 }
 #[cfg(feature = "udp")]

tokio/src/runtime/mod.rs

@@ -2,7 +2,7 @@
 //!
 //! Applications using Tokio require some runtime support in order to work:
 //!
-//! * A [reactor] to drive I/O resources.
+//! * A [driver] to drive I/O resources.
 //! * An [executor] to execute tasks that use these I/O resources.
 //! * A [timer] for scheduling work to run after a set period of time.
 //!
@@ -128,7 +128,7 @@
 //! }
 //! ```
 //!
-//! [reactor]: ../reactor/struct.Reactor.html
+//! [driver]: tokio_net::driver
 //! [executor]: https://tokio.rs/docs/internals/runtime-model/#executors
 //! [timer]: ../timer/index.html
 //! [`Runtime`]: struct.Runtime.html
@@ -138,6 +138,7 @@
 //! [idle]: struct.Runtime.html#method.shutdown_on_idle
 //! [`tokio::spawn`]: ../executor/fn.spawn.html
 //! [`Timer`]: https://docs.rs/tokio-timer/0.2/tokio_timer/timer/struct.Timer.html
+//! [`tokio::main`]: ../../tokio_macros/attr.main.html
 
 pub mod current_thread;
 mod threadpool;

tokio/src/stream.rs

@@ -23,7 +23,8 @@ pub use futures_util::stream::{empty, iter, once, pending, poll_fn, repeat, unfo
 /// This trait can be imported directly or via the Tokio prelude: `use
 /// tokio::prelude::*`.
 ///
-/// [`timeout`]: #method.timeout
+/// [`throttle`]: method.throttle
+/// [`timeout`]: method.timeout
 pub trait StreamExt: Stream {
     /// Throttle down the stream by enforcing a fixed delay between items.
     ///