From 68d5fcb8d154309ba5abeaf8f092835ff3fa7c52 Mon Sep 17 00:00:00 2001 From: Ivan Petkov Date: Sun, 18 Aug 2019 14:38:55 -0700 Subject: [PATCH] docs: fix all rustdoc warnings (#1474) --- azure-pipelines.yml | 28 +++++++++++++----------- ci/azure-deploy-docs.yml | 5 +++-- tokio-executor/src/typed.rs | 1 + tokio-io/src/async_read.rs | 2 +- tokio-io/src/io/buf_reader.rs | 3 --- tokio-io/src/io/buf_writer.rs | 2 +- tokio-io/src/io/flush.rs | 2 -- tokio-io/src/io/mod.rs | 38 --------------------------------- tokio-io/src/io/read_exact.rs | 4 +--- tokio-io/src/io/shutdown.rs | 2 -- tokio-net/src/tcp/listener.rs | 4 +++- tokio-net/src/tcp/stream.rs | 4 +++- tokio-net/src/udp/mod.rs | 4 ++-- tokio-net/src/udp/socket.rs | 4 +++- tokio-net/src/uds/datagram.rs | 4 +++- tokio-net/src/uds/listener.rs | 4 +++- tokio-net/src/uds/stream.rs | 4 +++- tokio-test/src/io.rs | 3 +++ tokio-timer/src/clock/mod.rs | 10 ++++----- tokio-timer/src/clock/now.rs | 2 +- tokio-timer/src/lib.rs | 4 ++-- tokio-timer/src/timer/handle.rs | 2 +- tokio-timer/src/timer/mod.rs | 16 +++++++------- tokio/src/lib.rs | 3 ++- tokio/src/net.rs | 6 ------ tokio/src/runtime/mod.rs | 5 +++-- tokio/src/stream.rs | 3 ++- 27 files changed, 69 insertions(+), 100 deletions(-) diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 61b0ef224..bfa690892 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -115,16 +115,18 @@ jobs: # parameters: # name: tsan # rust: $(nightly) -# -# - template: ci/azure-deploy-docs.yml -# parameters: -# dependsOn: -# - rustfmt -# - test_tokio -# - test_sub_cross -# - test_linux -# - features -# - test_nightly -# - cross_32bit_linux -# - minrust -# - tsan + +- template: ci/azure-deploy-docs.yml + parameters: + rust: $(nightly) + dependsOn: + - rustfmt + - clippy + - test_tokio + - test_sub_cross + - test_linux + - test_features +# - test_nightly +# - cross_32bit_linux +# - minrust +# - tsan diff --git a/ci/azure-deploy-docs.yml b/ci/azure-deploy-docs.yml index ebd067b33..77ec1b0f6 100644 --- a/ci/azure-deploy-docs.yml +++ b/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: | diff --git a/tokio-executor/src/typed.rs b/tokio-executor/src/typed.rs index a1125a126..2110d622f 100644 --- a/tokio-executor/src/typed.rs +++ b/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)] /// diff --git a/tokio-io/src/async_read.rs b/tokio-io/src/async_read.rs index 2fbac2adb..97ca2b93c 100644 --- a/tokio-io/src/async_read.rs +++ b/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 { diff --git a/tokio-io/src/io/buf_reader.rs b/tokio-io/src/io/buf_reader.rs index b8347d09c..7f0fdd7c7 100644 --- a/tokio-io/src/io/buf_reader.rs +++ b/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 { inner: R, diff --git a/tokio-io/src/io/buf_writer.rs b/tokio-io/src/io/buf_writer.rs index c91cb6fd5..438bc653b 100644 --- a/tokio-io/src/io/buf_writer.rs +++ b/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 diff --git a/tokio-io/src/io/flush.rs b/tokio-io/src/io/flush.rs index 6be90fcc2..6a78fb3c3 100644 --- a/tokio-io/src/io/flush.rs +++ b/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, diff --git a/tokio-io/src/io/mod.rs b/tokio-io/src/io/mod.rs index 8e05bb085..888f65486 100644 --- a/tokio-io/src/io/mod.rs +++ b/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; diff --git a/tokio-io/src/io/read_exact.rs b/tokio-io/src/io/read_exact.rs index 6a616b97a..28b65118a 100644 --- a/tokio-io/src/io/read_exact.rs +++ b/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. -/// -/// [`read_exact`]: fn.read_exact.html +/// Created by the [`AsyncRead::read_exact`]. pub(crate) fn read_exact<'a, A>(reader: &'a mut A, buf: &'a mut [u8]) -> ReadExact<'a, A> where A: AsyncRead + Unpin + ?Sized, diff --git a/tokio-io/src/io/shutdown.rs b/tokio-io/src/io/shutdown.rs index f22c6e551..5bc216e4e 100644 --- a/tokio-io/src/io/shutdown.rs +++ b/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, diff --git a/tokio-net/src/tcp/listener.rs b/tokio-net/src/tcp/listener.rs index e90cac9c8..147086100 100644 --- a/tokio-net/src/tcp/listener.rs +++ b/tokio-net/src/tcp/listener.rs @@ -262,8 +262,10 @@ impl TryFrom 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 { value.io.into_inner() } diff --git a/tokio-net/src/tcp/stream.rs b/tokio-net/src/tcp/stream.rs index fb22ab346..0971e55e9 100644 --- a/tokio-net/src/tcp/stream.rs +++ b/tokio-net/src/tcp/stream.rs @@ -802,8 +802,10 @@ impl TryFrom 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 { value.io.into_inner() } diff --git a/tokio-net/src/udp/mod.rs b/tokio-net/src/udp/mod.rs index 156f9573a..e5c065854 100644 --- a/tokio-net/src/udp/mod.rs +++ b/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; diff --git a/tokio-net/src/udp/socket.rs b/tokio-net/src/udp/socket.rs index 1b26a68a5..90d1c1e90 100644 --- a/tokio-net/src/udp/socket.rs +++ b/tokio-net/src/udp/socket.rs @@ -328,8 +328,10 @@ impl TryFrom 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 { value.io.into_inner() } diff --git a/tokio-net/src/uds/datagram.rs b/tokio-net/src/uds/datagram.rs index d9ebe24f6..445c713fb 100644 --- a/tokio-net/src/uds/datagram.rs +++ b/tokio-net/src/uds/datagram.rs @@ -201,8 +201,10 @@ impl TryFrom 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 { value.io.into_inner() } diff --git a/tokio-net/src/uds/listener.rs b/tokio-net/src/uds/listener.rs index 75c7e867c..9c1802745 100644 --- a/tokio-net/src/uds/listener.rs +++ b/tokio-net/src/uds/listener.rs @@ -102,8 +102,10 @@ impl TryFrom 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 { value.io.into_inner() } diff --git a/tokio-net/src/uds/stream.rs b/tokio-net/src/uds/stream.rs index daa02246b..9858184a7 100644 --- a/tokio-net/src/uds/stream.rs +++ b/tokio-net/src/uds/stream.rs @@ -131,8 +131,10 @@ impl TryFrom 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 { value.io.into_inner() } diff --git a/tokio-test/src/io.rs b/tokio-test/src/io.rs index 468190913..ffbb07c53 100644 --- a/tokio-test/src/io.rs +++ b/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; diff --git a/tokio-timer/src/clock/mod.rs b/tokio-timer/src/clock/mod.rs index cb15c3798..a4cd2b3f6 100644 --- a/tokio-timer/src/clock/mod.rs +++ b/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::now`]: https://doc.rust-lang.org/std/time/struct.Instant.html#method.now +//! [`Instant`]: std::time::Instant +//! [`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::now`]: https://doc.rust-lang.org/std/time/struct.Instant.html#method.now +/// [`Instant`]: std::time::Instant +/// [`Instant::now`]: std::time::Instant::now #[derive(Default, Clone)] pub struct Clock { now: Option>, @@ -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 } } diff --git a/tokio-timer/src/clock/now.rs b/tokio-timer/src/clock/now.rs index 18450c830..f6b11b706 100644 --- a/tokio-timer/src/clock/now.rs +++ b/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; diff --git a/tokio-timer/src/lib.rs b/tokio-timer/src/lib.rs index da046b07d..9868fcb62 100644 --- a/tokio-timer/src/lib.rs +++ b/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; diff --git a/tokio-timer/src/timer/handle.rs b/tokio-timer/src/timer/handle.rs index 596d63315..a6ddfd341 100644 --- a/tokio-timer/src/timer/handle.rs +++ b/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 = diff --git a/tokio-timer/src/timer/mod.rs b/tokio-timer/src/timer/mod.rs index 8c7f540b1..1a25ef0ac 100644 --- a/tokio-timer/src/timer/mod.rs +++ b/tokio-timer/src/timer/mod.rs @@ -23,12 +23,12 @@ //! //! [`Timer`]: struct.Timer.html //! [`Handle`]: struct.Handle.html -//! [`Delay`]: ../struct.Delay.html -//! [`Now`]: ../clock/trait.Now.html -//! [`Now::now`]: ../clock/trait.Now.html#method.now +//! [`Delay`]: Delay +//! [`Now`]: clock::Now +//! [`Now::now`]: clock::Now::now //! [`SystemNow`]: struct.SystemNow.html -//! [`Instant`]: https://doc.rust-lang.org/std/time/struct.Instant.html -//! [`Instant::now`]: https://doc.rust-lang.org/std/time/struct.Instant.html#method.now +//! [`Instant`]: std::time::Instant +//! [`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 -/// [`Interval`]: ../struct.Interval.html -/// [`Timeout`]: ../struct.Timeout.html +/// [`Delay`]: struct.Delay.html +/// [`Interval`]: struct.Interval.html +/// [`Timeout`]: struct.Timeout.html /// [paper]: http://www.cs.columbia.edu/~nahum/w6998/papers/ton97-timing-wheels.pdf /// [`handle`]: #method.handle /// [`turn`]: #method.turn diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs index d2701d337..b1255ece8 100644 --- a/tokio/src/lib.rs +++ b/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 diff --git a/tokio/src/net.rs b/tokio/src/net.rs index ca9db00e7..586fe65bb 100644 --- a/tokio/src/net.rs +++ b/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")] diff --git a/tokio/src/runtime/mod.rs b/tokio/src/runtime/mod.rs index ac17461d7..cc4131a4e 100644 --- a/tokio/src/runtime/mod.rs +++ b/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; diff --git a/tokio/src/stream.rs b/tokio/src/stream.rs index 1fd190226..5b72077b3 100644 --- a/tokio/src/stream.rs +++ b/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. ///