From 40aaba5c52ede3d8ff2a78b716acc289d648f0e0 Mon Sep 17 00:00:00 2001 From: Mikail Bagishov Date: Sun, 31 May 2020 00:18:02 +0300 Subject: [PATCH 1/2] Update doc comments --- tokio/src/future/ready.rs | 2 +- tokio/src/io/util/flush.rs | 3 ++- tokio/src/io/util/read_buf.rs | 2 +- tokio/src/io/util/read_exact.rs | 3 ++- tokio/src/io/util/shutdown.rs | 3 ++- tokio/src/runtime/context.rs | 4 ++-- tokio/src/time/driver/mod.rs | 27 ++++++++++++++++----------- 7 files changed, 26 insertions(+), 18 deletions(-) diff --git a/tokio/src/future/ready.rs b/tokio/src/future/ready.rs index d74f999e5de..de2d60c13a2 100644 --- a/tokio/src/future/ready.rs +++ b/tokio/src/future/ready.rs @@ -2,7 +2,7 @@ use std::future::Future; use std::pin::Pin; use std::task::{Context, Poll}; -/// Future for the [`ready`](ready()) function. +/// Future for the [`ok`](ok()) function. /// /// `pub` in order to use the future as an associated type in a sealed trait. #[derive(Debug)] diff --git a/tokio/src/io/util/flush.rs b/tokio/src/io/util/flush.rs index 1465f304486..534a5160c1a 100644 --- a/tokio/src/io/util/flush.rs +++ b/tokio/src/io/util/flush.rs @@ -8,7 +8,8 @@ use std::task::{Context, Poll}; cfg_io_util! { /// A future used to fully flush an I/O object. /// - /// Created by the [`AsyncWriteExt::flush`] function. + /// Created by the [`AsyncWriteExt::flush`][flush] function. + /// [flush]: crate::io::AsyncWriteExt::flush #[derive(Debug)] pub struct Flush<'a, A: ?Sized> { a: &'a mut A, diff --git a/tokio/src/io/util/read_buf.rs b/tokio/src/io/util/read_buf.rs index 550499b9334..723ea66061e 100644 --- a/tokio/src/io/util/read_buf.rs +++ b/tokio/src/io/util/read_buf.rs @@ -15,7 +15,7 @@ where } cfg_io_util! { - /// Future returned by [`read_buf`](AsyncReadExt::read_buf). + /// Future returned by [`read_buf`](crate::io::AsyncReadExt::read_buf). #[derive(Debug)] #[must_use = "futures do nothing unless you `.await` or poll them"] pub struct ReadBuf<'a, R, B> { diff --git a/tokio/src/io/util/read_exact.rs b/tokio/src/io/util/read_exact.rs index d6983c99530..86b8412954b 100644 --- a/tokio/src/io/util/read_exact.rs +++ b/tokio/src/io/util/read_exact.rs @@ -9,7 +9,8 @@ use std::task::{Context, Poll}; /// A future which can be used to easily read exactly enough bytes to fill /// a buffer. /// -/// Created by the [`AsyncRead::read_exact`]. +/// Created by the [`AsyncReadExt::read_exact`][read_exact]. +/// [read_exact]: [crate::io::AsyncReadExt::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/src/io/util/shutdown.rs b/tokio/src/io/util/shutdown.rs index f24e2885414..33ac0ac0db7 100644 --- a/tokio/src/io/util/shutdown.rs +++ b/tokio/src/io/util/shutdown.rs @@ -8,7 +8,8 @@ use std::task::{Context, Poll}; cfg_io_util! { /// A future used to shutdown an I/O object. /// - /// Created by the [`AsyncWriteExt::shutdown`] function. + /// Created by the [`AsyncWriteExt::shutdown`][shutdown] function. + /// [shutdown]: crate::io::AsyncWriteExt::shutdown #[derive(Debug)] pub struct Shutdown<'a, A: ?Sized> { a: &'a mut A, diff --git a/tokio/src/runtime/context.rs b/tokio/src/runtime/context.rs index 4af2df23eb7..1b267f481e2 100644 --- a/tokio/src/runtime/context.rs +++ b/tokio/src/runtime/context.rs @@ -47,9 +47,9 @@ cfg_rt_core! { } } -/// Set this [`ThreadContext`] as the current active [`ThreadContext`]. +/// Set this [`Handle`] as the current active [`Handle`]. /// -/// [`ThreadContext`]: struct@ThreadContext +/// [`Handle`]: Handle pub(crate) fn enter(new: Handle, f: F) -> R where F: FnOnce() -> R, diff --git a/tokio/src/time/driver/mod.rs b/tokio/src/time/driver/mod.rs index 4616816f3f4..66a55c369c0 100644 --- a/tokio/src/time/driver/mod.rs +++ b/tokio/src/time/driver/mod.rs @@ -26,29 +26,29 @@ use std::sync::Arc; use std::usize; use std::{cmp, fmt}; -/// Time implementation that drives [`Delay`], [`Interval`], and [`Timeout`]. +/// Time implementation that drives [`Delay`][delay], [`Interval`][interval], and [`Timeout`][timeout]. /// /// A `Driver` instance tracks the state necessary for managing time and -/// notifying the [`Delay`] instances once their deadlines are reached. +/// notifying the [`Delay`][delay] instances once their deadlines are reached. /// -/// It is expected that a single instance manages many individual [`Delay`] +/// It is expected that a single instance manages many individual [`Delay`][delay] /// instances. The `Driver` implementation is thread-safe and, as such, is able /// to handle callers from across threads. /// -/// After creating the `Driver` instance, the caller must repeatedly call -/// [`turn`]. The time driver will perform no work unless [`turn`] is called -/// repeatedly. +/// After creating the `Driver` instance, the caller must repeatedly call `park` +/// or `park_timeout`. The time driver will perform no work unless `park` or +/// `park_timeout` is called repeatedly. /// /// The driver has a resolution of one millisecond. Any unit of time that falls /// between milliseconds are rounded up to the next millisecond. /// -/// When an instance is dropped, any outstanding [`Delay`] instance that has not +/// When an instance is dropped, any outstanding [`Delay`][delay] instance that has not /// elapsed will be notified with an error. At this point, calling `poll` on the -/// [`Delay`] instance will result in `Err` being returned. +/// [`Delay`][delay] instance will result in panic. /// /// # Implementation /// -/// THe time driver is based on the [paper by Varghese and Lauck][paper]. +/// The time driver is based on the [paper by Varghese and Lauck][paper]. /// /// A hashed timing wheel is a vector of slots, where each slot handles a time /// slice. As time progresses, the timer walks over the slot for the current @@ -73,9 +73,14 @@ use std::{cmp, fmt}; /// When the timer processes entries at level zero, it will notify all the /// `Delay` instances as their deadlines have been reached. For all higher /// levels, all entries will be redistributed across the wheel at the next level -/// down. Eventually, as time progresses, entries will [`Delay`] instances will +/// down. Eventually, as time progresses, entries will [`Delay`][delay] instances will /// either be canceled (dropped) or their associated entries will reach level /// zero and be notified. +/// +/// [paper]: http://www.cs.columbia.edu/~nahum/w6998/papers/ton97-timing-wheels.pdf +/// [delay]: crate::time::Delay +/// [timeout]: crate::time::Timeout +/// [interval]: crate::time::Interval #[derive(Debug)] pub(crate) struct Driver { /// Shared state @@ -119,7 +124,7 @@ where T: Park, { /// Creates a new `Driver` instance that uses `park` to block the current - /// thread and `now` to get the current `Instant`. + /// thread and `clock` to get the current `Instant`. /// /// Specifying the source of time is useful when testing. pub(crate) fn new(park: T, clock: Clock) -> Driver { From 7ac2e0318b17a2ee8429c85b08bfef6d1be78c90 Mon Sep 17 00:00:00 2001 From: Mikail Bagishov Date: Sun, 31 May 2020 15:30:06 +0300 Subject: [PATCH 2/2] Remove trailing whitespace --- tokio/src/time/driver/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tokio/src/time/driver/mod.rs b/tokio/src/time/driver/mod.rs index 66a55c369c0..554042fccdc 100644 --- a/tokio/src/time/driver/mod.rs +++ b/tokio/src/time/driver/mod.rs @@ -36,7 +36,7 @@ use std::{cmp, fmt}; /// to handle callers from across threads. /// /// After creating the `Driver` instance, the caller must repeatedly call `park` -/// or `park_timeout`. The time driver will perform no work unless `park` or +/// or `park_timeout`. The time driver will perform no work unless `park` or /// `park_timeout` is called repeatedly. /// /// The driver has a resolution of one millisecond. Any unit of time that falls