docs: use third form in API docs (#2027)

tokio-test/src/macros.rs

@@ -1,6 +1,6 @@
 //! A collection of useful macros for testing futures and tokio based code
 
-/// Assert a `Poll` is ready, returning the value.
+/// Asserts a `Poll` is ready, returning the value.
 ///
 /// This will invoke `panic!` if the provided `Poll` does not evaluate to `Poll::Ready` at
 /// runtime.
@@ -39,7 +39,7 @@ macro_rules! assert_ready {
     }};
 }
 
-/// Assert a `Poll<Result<...>>` is ready and `Ok`, returning the value.
+/// Asserts a `Poll<Result<...>>` is ready and `Ok`, returning the value.
 ///
 /// This will invoke `panic!` if the provided `Poll` does not evaluate to `Poll::Ready(Ok(..))` at
 /// runtime.
@@ -72,7 +72,7 @@ macro_rules! assert_ready_ok {
     }};
 }
 
-/// Assert a `Poll<Result<...>>` is ready and `Err`, returning the error.
+/// Asserts a `Poll<Result<...>>` is ready and `Err`, returning the error.
 ///
 /// This will invoke `panic!` if the provided `Poll` does not evaluate to `Poll::Ready(Err(..))` at
 /// runtime.
@@ -105,7 +105,7 @@ macro_rules! assert_ready_err {
     }};
 }
 
-/// Assert a `Poll` is pending.
+/// Asserts a `Poll` is pending.
 ///
 /// This will invoke `panic!` if the provided `Poll` does not evaluate to `Poll::Pending` at
 /// runtime.
@@ -144,7 +144,7 @@ macro_rules! assert_pending {
     }};
 }
 
-/// Assert if a poll is ready and check for equality on the value
+/// Asserts if a poll is ready and check for equality on the value
 ///
 /// This will invoke `panic!` if the provided `Poll` does not evaluate to `Poll::Ready` at
 /// runtime and the value produced does not partially equal the expected value.

tokio-test/src/task.rs

@@ -45,7 +45,7 @@ const WAKE: usize = 1;
 const SLEEP: usize = 2;
 
 impl<T> Spawn<T> {
-    /// Consume `self` returning the inner value
+    /// Consumes `self` returning the inner value
     pub fn into_inner(mut self) -> T
     where
         T: Unpin,
@@ -101,7 +101,7 @@ impl<T: Unpin> ops::DerefMut for Spawn<T> {
 }
 
 impl<T: Future> Spawn<T> {
-    /// Poll a future
+    /// Polls a future
     pub fn poll(&mut self) -> Poll<T::Output> {
         let fut = self.future.as_mut();
         self.task.enter(|cx| fut.poll(cx))
@@ -109,7 +109,7 @@ impl<T: Future> Spawn<T> {
 }
 
 impl<T: Stream> Spawn<T> {
-    /// Poll a stream
+    /// Polls a stream
     pub fn poll_next(&mut self) -> Poll<Option<T::Item>> {
         let stream = self.future.as_mut();
         self.task.enter(|cx| stream.poll_next(cx))
@@ -117,14 +117,14 @@ impl<T: Stream> Spawn<T> {
 }
 
 impl MockTask {
-    /// Create a new mock task
+    /// Creates new mock task
     fn new() -> Self {
         MockTask {
             waker: Arc::new(ThreadWaker::new()),
         }
     }
 
-    /// Run a closure from the context of the task.
+    /// Runs a closure from the context of the task.
     ///
     /// Any wake notifications resulting from the execution of the closure are
     /// tracked.
@@ -190,8 +190,7 @@ impl ThreadWaker {
     }
 
     fn wake(&self) {
-        // First, try transitioning from IDLE -> NOTIFY, this does not require a
-        // lock.
+        // First, try transitioning from IDLE -> NOTIFY, this does not require a lock.
         let mut state = self.state.lock().unwrap();
         let prev = *state;
 

tokio/src/fs/create_dir_all.rs

@@ -3,7 +3,7 @@ use crate::fs::asyncify;
 use std::io;
 use std::path::Path;
 
-/// Recursively create a directory and all of its parent components if they
+/// Recursively creates a directory and all of its parent components if they
 /// are missing.
 ///
 /// This is an async version of [`std::fs::create_dir_all`][std]

tokio/src/fs/file.rs

@@ -155,7 +155,7 @@ impl File {
         Ok(File::from_std(std_file))
     }
 
-    /// Convert a [`std::fs::File`][std] to a [`tokio::fs::File`][file].
+    /// Converts a [`std::fs::File`][std] to a [`tokio::fs::File`][file].
     ///
     /// [std]: std::fs::File
     /// [file]: File
@@ -176,7 +176,7 @@ impl File {
         }
     }
 
-    /// Seek to an offset, in bytes, in a stream.
+    /// Seeks to an offset, in bytes, in a stream.
     ///
     /// # Examples
     ///

tokio/src/fs/metadata.rs

@@ -4,7 +4,7 @@ use std::fs::Metadata;
 use std::io;
 use std::path::Path;
 
-/// Given a path, query the file system to get information about a file,
+/// Given a path, queries the file system to get information about a file,
 /// directory, etc.
 ///
 /// This is an async version of [`std::fs::metadata`][std]

tokio/src/fs/read.rs

@@ -2,7 +2,7 @@ use crate::fs::asyncify;
 
 use std::{io, path::Path};
 
-/// Read the entire contents of a file into a bytes vector.
+/// Reads the entire contents of a file into a bytes vector.
 ///
 /// This is an async version of [`std::fs::read`][std]
 ///

tokio/src/fs/read_dir.rs

@@ -165,7 +165,7 @@ impl DirEntry {
         self.0.file_name()
     }
 
-    /// Return the metadata for the file that this entry points at.
+    /// Returns the metadata for the file that this entry points at.
     ///
     /// This function will not traverse symlinks if this entry points at a
     /// symlink.
@@ -200,7 +200,7 @@ impl DirEntry {
         asyncify(move || std.metadata()).await
     }
 
-    /// Return the file type for the file that this entry points at.
+    /// Returns the file type for the file that this entry points at.
     ///
     /// This function will not traverse symlinks if this entry points at a
     /// symlink.

tokio/src/fs/rename.rs

@@ -3,7 +3,7 @@ use crate::fs::asyncify;
 use std::io;
 use std::path::Path;
 
-/// Rename a file or directory to a new name, replacing the original file if
+/// Renames a file or directory to a new name, replacing the original file if
 /// `to` already exists.
 ///
 /// This will not work if the new name is on a different mount point.

tokio/src/future/maybe_done.rs

@@ -40,7 +40,7 @@ impl<Fut: Future> MaybeDone<Fut> {
         }
     }
 
-    /// Attempt to take the output of a `MaybeDone` without driving it
+    /// Attempts to take the output of a `MaybeDone` without driving it
     /// towards completion.
     #[inline]
     pub fn take_output(self: Pin<&mut Self>) -> Option<Fut::Output> {

tokio/src/future/ready.rs

@@ -21,7 +21,7 @@ impl<T> Future for Ready<T> {
     }
 }
 
-/// Create a future that is immediately ready with a success value.
+/// Creates a future that is immediately ready with a success value.
 pub(crate) fn ok<T, E>(t: T) -> Ready<Result<T, E>> {
     Ready(Some(Ok(t)))
 }

tokio/src/io/async_buf_read.rs

@@ -5,7 +5,7 @@ use std::ops::DerefMut;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-/// Read bytes asynchronously.
+/// Reads bytes asynchronously.
 ///
 /// This trait inherits from [`std::io::BufRead`] and indicates that an I/O object is
 /// **non-blocking**. All non-blocking I/O objects must return an error when
@@ -17,7 +17,7 @@ use std::task::{Context, Poll};
 /// [`std::io::BufRead`]: std::io::BufRead
 /// [`AsyncBufReadExt`]: crate::io::AsyncBufReadExt
 pub trait AsyncBufRead: AsyncRead {
-    /// Attempt to return the contents of the internal buffer, filling it with more data
+    /// Attempts to return the contents of the internal buffer, filling it with more data
     /// from the inner reader if it is empty.
     ///
     /// On success, returns `Poll::Ready(Ok(buf))`.

tokio/src/io/async_read.rs

@@ -5,7 +5,7 @@ use std::ops::DerefMut;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-/// Read bytes from a source.
+/// Reads bytes from a source.
 ///
 /// This trait is analogous to the [`std::io::Read`] trait, but integrates with
 /// the asynchronous task system. In particular, the [`poll_read`] method,
@@ -82,7 +82,7 @@ pub trait AsyncRead {
         true
     }
 
-    /// Attempt to read from the `AsyncRead` into `buf`.
+    /// Attempts to read from the `AsyncRead` into `buf`.
     ///
     /// On success, returns `Poll::Ready(Ok(num_bytes_read))`.
     ///
@@ -96,7 +96,7 @@ pub trait AsyncRead {
         buf: &mut [u8],
     ) -> Poll<io::Result<usize>>;
 
-    /// Pull some bytes from this source into the specified `BufMut`, returning
+    /// Pulls some bytes from this source into the specified `BufMut`, returning
     /// how many bytes were read.
     ///
     /// The `buf` provided will have bytes read into it and the internal cursor

tokio/src/io/async_seek.rs

@@ -16,7 +16,7 @@ use std::task::{Context, Poll};
 /// [`Seek::seek`]: std::io::Seek::seek()
 /// [`AsyncSeekExt`]: crate::io::AsyncSeekExt
 pub trait AsyncSeek {
-    /// Attempt to seek to an offset, in bytes, in a stream.
+    /// Attempts to seek to an offset, in bytes, in a stream.
     ///
     /// A seek beyond the end of a stream is allowed, but behavior is defined
     /// by the implementation.
@@ -29,7 +29,7 @@ pub trait AsyncSeek {
         position: SeekFrom,
     ) -> Poll<io::Result<()>>;
 
-    /// Wait for a seek operation to complete.
+    /// Waits for a seek operation to complete.
     ///
     /// If the seek operation completed successfully,
     /// this method returns the new position from the start of the stream.

tokio/src/io/async_write.rs

@@ -58,7 +58,7 @@ pub trait AsyncWrite {
         buf: &[u8],
     ) -> Poll<Result<usize, io::Error>>;
 
-    /// Attempt to flush the object, ensuring that any buffered data reach
+    /// Attempts to flush the object, ensuring that any buffered data reach
     /// their destination.
     ///
     /// On success, returns `Poll::Ready(Ok(()))`.
@@ -129,7 +129,7 @@ pub trait AsyncWrite {
     /// task.
     fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), io::Error>>;
 
-    /// Write a `Buf` into this value, returning how many bytes were written.
+    /// Writes a `Buf` into this value, returning how many bytes were written.
     ///
     /// Note that this method will advance the `buf` provided automatically by
     /// the number of bytes written.

tokio/src/io/blocking.rs

@@ -16,7 +16,7 @@ use self::State::*;
 pub(crate) struct Blocking<T> {
     inner: Option<T>,
     state: State<T>,
-    /// true if the lower IO layer needs flushing
+    /// `true` if the lower IO layer needs flushing
     need_flush: bool,
 }
 

tokio/src/io/driver/mod.rs

@@ -236,7 +236,7 @@ impl fmt::Debug for Handle {
 // ===== impl Inner =====
 
 impl Inner {
-    /// Register an I/O resource with the reactor.
+    /// Registers an I/O resource with the reactor.
     ///
     /// The registration token is returned.
     pub(super) fn add_source(&self, source: &dyn Evented) -> io::Result<Address> {

tokio/src/io/poll_evented.rs

@@ -212,7 +212,7 @@ where
         Ok(io)
     }
 
-    /// Check the I/O resource's read readiness state.
+    /// Checks the I/O resource's read readiness state.
     ///
     /// The mask argument allows specifying what readiness to notify on. This
     /// can be any value, including platform specific readiness, **except**
@@ -280,12 +280,12 @@ where
         Ok(())
     }
 
-    /// Check the I/O resource's write readiness state.
+    /// Checks the I/O resource's write readiness state.
     ///
     /// This always checks for writable readiness and also checks for HUP
     /// readiness on platforms that support it.
     ///
-    /// If the resource is not ready for a write then `Async::NotReady` is
+    /// If the resource is not ready for a write then `Poll::Pending` is
     /// returned and the current task is notified once a new event is received.
     ///
     /// The I/O resource will remain in a write-ready state until readiness is

tokio/src/io/registration.rs

@@ -47,7 +47,7 @@ cfg_io_driver! {
 // ===== impl Registration =====
 
 impl Registration {
-    /// Register the I/O resource with the default reactor.
+    /// Registers the I/O resource with the default reactor.
     ///
     /// # Return
     ///
@@ -79,7 +79,7 @@ impl Registration {
         Ok(Registration { handle, address })
     }
 
-    /// Deregister the I/O resource from the reactor it is associated with.
+    /// Deregisters the I/O resource from the reactor it is associated with.
     ///
     /// This function must be called before the I/O resource associated with the
     /// registration is dropped.
@@ -106,7 +106,7 @@ impl Registration {
         inner.deregister_source(io)
     }
 
-    /// Poll for events on the I/O resource's read readiness stream.
+    /// Polls for events on the I/O resource's read readiness stream.
     ///
     /// If the I/O resource receives a new read readiness event since the last
     /// call to `poll_read_ready`, it is returned. If it has not, the current
@@ -157,7 +157,7 @@ impl Registration {
         self.poll_ready(Direction::Read, None)
     }
 
-    /// Poll for events on the I/O resource's write readiness stream.
+    /// Polls for events on the I/O resource's write readiness stream.
     ///
     /// If the I/O resource receives a new write readiness event since the last
     /// call to `poll_write_ready`, it is returned. If it has not, the current
@@ -197,7 +197,7 @@ impl Registration {
         }
     }
 
-    /// Consume any pending write readiness event.
+    /// Consumes any pending write readiness event.
     ///
     /// This function is identical to [`poll_write_ready`] **except** that it
     /// will not notify the current task when a new event is received. As such,
@@ -208,7 +208,7 @@ impl Registration {
         self.poll_ready(Direction::Write, None)
     }
 
-    /// Poll for events on the I/O resource's `direction` readiness stream.
+    /// Polls for events on the I/O resource's `direction` readiness stream.
     ///
     /// If called with a task context, notify the task when a new event is
     /// received.

tokio/src/io/split.rs

@@ -27,7 +27,7 @@ cfg_io_util! {
         inner: Arc<Inner<T>>,
     }
 
-    /// Split a single value implementing `AsyncRead + AsyncWrite` into separate
+    /// Splits a single value implementing `AsyncRead + AsyncWrite` into separate
     /// `AsyncRead` and `AsyncWrite` handles.
     ///
     /// To restore this read/write object from its `ReadHalf` and
@@ -61,13 +61,13 @@ struct Guard<'a, T> {
 }
 
 impl<T> ReadHalf<T> {
-    /// Check if this `ReadHalf` and some `WriteHalf` were split from the same
+    /// Checks if this `ReadHalf` and some `WriteHalf` were split from the same
     /// stream.
     pub fn is_pair_of(&self, other: &WriteHalf<T>) -> bool {
         other.is_pair_of(&self)
     }
 
-    /// Reunite with a previously split `WriteHalf`.
+    /// Reunites with a previously split `WriteHalf`.
     ///
     /// # Panics
     ///
@@ -81,7 +81,7 @@ impl<T> ReadHalf<T> {
 
             let inner = Arc::try_unwrap(self.inner)
                 .ok()
-                .expect("Arc::try_unwrap failed");
+                .expect("`Arc::try_unwrap` failed");
 
             inner.stream.into_inner()
         } else {

tokio/src/io/util/async_buf_read_ext.rs

@@ -9,7 +9,7 @@ cfg_io_util! {
     ///
     /// [`AsyncBufRead`]: crate::io::AsyncBufRead
     pub trait AsyncBufReadExt: AsyncBufRead {
-        /// Read all bytes into `buf` until the delimiter `byte` or EOF is reached.
+        /// Reads all bytes into `buf` until the delimiter `byte` or EOF is reached.
         ///
         /// Equivalent to:
         ///
@@ -85,7 +85,7 @@ cfg_io_util! {
             read_until(self, byte, buf)
         }
 
-        /// Read all bytes until a newline (the 0xA byte) is reached, and append
+        /// Reads all bytes until a newline (the 0xA byte) is reached, and append
         /// them to the provided buffer.
         ///
         /// Equivalent to:

tokio/src/io/util/async_read_ext.rs

@@ -12,7 +12,7 @@ use crate::io::AsyncRead;
 use bytes::BufMut;
 
 cfg_io_util! {
-    /// Define numeric reader
+    /// Defines numeric reader
     macro_rules! read_impl {
         (
             $(
@@ -29,7 +29,7 @@ cfg_io_util! {
         }
     }
 
-    /// Read bytes from a source.
+    /// Reads bytes from a source.
     ///
     /// Implemented as an extention trait, adding utility methods to all
     /// [`AsyncRead`] types. Callers will tend to import this trait instead of
@@ -58,7 +58,7 @@ cfg_io_util! {
     /// [`AsyncRead`]: AsyncRead
     /// [`prelude`]: crate::prelude
     pub trait AsyncReadExt: AsyncRead {
-        /// Create a new `AsyncRead` instance that chains this stream with
+        /// Creates a new `AsyncRead` instance that chains this stream with
         /// `next`.
         ///
         /// The returned `AsyncRead` instance will first read all bytes from this object
@@ -95,7 +95,7 @@ cfg_io_util! {
             chain(self, next)
         }
 
-        /// Pull some bytes from this source into the specified buffer,
+        /// Pulls some bytes from this source into the specified buffer,
         /// returning how many bytes were read.
         ///
         /// Equivalent to:
@@ -120,7 +120,7 @@ cfg_io_util! {
         ///
         /// No guarantees are provided about the contents of `buf` when this
         /// function is called, implementations cannot rely on any property of the
-        /// contents of `buf` being true. It is recommended that *implementations*
+        /// contents of `buf` being `true`. It is recommended that *implementations*
         /// only write data to `buf` instead of reading its contents.
         ///
         /// Correspondingly, however, *callers* of this method may not assume
@@ -162,7 +162,7 @@ cfg_io_util! {
             read(self, buf)
         }
 
-        /// Pull some bytes from this source into the specified buffer,
+        /// Pulls some bytes from this source into the specified buffer,
         /// advancing the buffer's internal cursor.
         ///
         /// Equivalent to:
@@ -227,7 +227,7 @@ cfg_io_util! {
             read_buf(self, buf)
         }
 
-        /// Read the exact number of bytes required to fill `buf`.
+        /// Reads the exact number of bytes required to fill `buf`.
         ///
         /// Equivalent to:
         ///
@@ -240,7 +240,7 @@ cfg_io_util! {
         ///
         /// No guarantees are provided about the contents of `buf` when this
         /// function is called, implementations cannot rely on any property of
-        /// the contents of `buf` being true. It is recommended that
+        /// the contents of `buf` being `true`. It is recommended that
         /// implementations only write data to `buf` instead of reading its
         /// contents.
         ///
@@ -671,7 +671,7 @@ cfg_io_util! {
             fn read_i128(&mut self) -> ReadI128;
         }
 
-        /// Read all bytes until EOF in this source, placing them into `buf`.
+        /// Reads all bytes until EOF in this source, placing them into `buf`.
         ///
         /// Equivalent to:
         ///
@@ -721,7 +721,7 @@ cfg_io_util! {
             read_to_end(self, buf)
         }
 
-        /// Read all bytes until EOF in this source, appending them to `buf`.
+        /// Reads all bytes until EOF in this source, appending them to `buf`.
         ///
         /// Equivalent to:
         ///

tokio/src/io/util/async_write_ext.rs

@@ -10,7 +10,7 @@ use crate::io::AsyncWrite;
 use bytes::Buf;
 
 cfg_io_util! {
-    /// Define numeric writer
+    /// Defines numeric writer
     macro_rules! write_impl {
         (
             $(
@@ -27,7 +27,7 @@ cfg_io_util! {
         }
     }
 
-    /// Write bytes to a sink.
+    /// Writes bytes to a sink.
     ///
     /// Implemented as an extention trait, adding utility methods to all
     /// [`AsyncWrite`] types. Callers will tend to import this trait instead of
@@ -60,7 +60,7 @@ cfg_io_util! {
     /// [`AsyncWrite`]: AsyncWrite
     /// [`prelude`]: crate::prelude
     pub trait AsyncWriteExt: AsyncWrite {
-        /// Write a buffer into this writer, returning how many bytes were
+        /// Writes a buffer into this writer, returning how many bytes were
         /// written.
         ///
         /// Equivalent to:
@@ -113,7 +113,7 @@ cfg_io_util! {
             write(self, src)
         }
 
-        /// Write a buffer into this writer, advancing the buffer's internal
+        /// Writes a buffer into this writer, advancing the buffer's internal
         /// cursor.
         ///
         /// Equivalent to:
@@ -610,7 +610,7 @@ cfg_io_util! {
             fn write_i128(&mut self, n: i128) -> WriteI128;
         }
 
-        /// Flush this output stream, ensuring that all intermediately buffered
+        /// Flushes this output stream, ensuring that all intermediately buffered
         /// contents reach their destination.
         ///
         /// Equivalent to:

tokio/src/io/util/buf_stream.rs

@@ -24,7 +24,7 @@ pin_project! {
 }
 
 impl<RW: AsyncRead + AsyncWrite> BufStream<RW> {
-    /// Wrap a type in both [`BufWriter`] and [`BufReader`].
+    /// Wraps a type in both [`BufWriter`] and [`BufReader`].
     ///
     /// See the documentation for those types and [`BufStream`] for details.
     pub fn new(stream: RW) -> BufStream<RW> {

tokio/src/loom/std/atomic_u32.rs

@@ -16,7 +16,7 @@ impl AtomicU32 {
         AtomicU32 { inner }
     }
 
-    /// Perform an unsynchronized load.
+    /// Performs an unsynchronized load.
     ///
     /// # Safety
     ///

tokio/src/loom/std/atomic_usize.rs

@@ -16,7 +16,7 @@ impl AtomicUsize {
         AtomicUsize { inner }
     }
 
-    /// Perform an unsynchronized load.
+    /// Performs an unsynchronized load.
     ///
     /// # Safety
     ///

tokio/src/macros/assert.rs

@@ -1,4 +1,4 @@
-/// Assert option is some
+/// Asserts option is some
 macro_rules! assert_some {
     ($e:expr) => {{
         match $e {
@@ -8,7 +8,7 @@ macro_rules! assert_some {
     }};
 }
 
-/// Assert option is none
+/// Asserts option is none
 macro_rules! assert_none {
     ($e:expr) => {{
         if let Some(v) = $e {

tokio/src/macros/cfg.rs

@@ -19,7 +19,7 @@ macro_rules! cfg_blocking {
     }
 }
 
-/// Enable blocking API internals
+/// Enables blocking API internals
 macro_rules! cfg_blocking_impl {
     ($($item:item)*) => {
         $(
@@ -35,7 +35,7 @@ macro_rules! cfg_blocking_impl {
     }
 }
 
-/// Enable blocking API internals
+/// Enables blocking API internals
 macro_rules! cfg_not_blocking_impl {
     ($($item:item)*) => {
         $(
@@ -51,7 +51,7 @@ macro_rules! cfg_not_blocking_impl {
     }
 }
 
-/// Enable internal `AtomicWaker` impl
+/// Enables internal `AtomicWaker` impl
 macro_rules! cfg_atomic_waker_impl {
     ($($item:item)*) => {
         $(

tokio/src/net/addr.rs

@@ -3,7 +3,7 @@ use crate::future;
 use std::io;
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6};
 
-/// Convert or resolve without blocking to one or more `SocketAddr` values.
+/// Converts or resolves without blocking to one or more `SocketAddr` values.
 ///
 /// # DNS
 ///

tokio/src/net/tcp/incoming.rs

@@ -17,7 +17,11 @@ impl Incoming<'_> {
         Incoming { inner: listener }
     }
 
-    #[doc(hidden)] // TODO: dox
+    /// Attempts to poll `TcpStream` by polling inner `TcpListener` to accept
+    /// connection.
+    ///
+    /// If `TcpListener` isn't ready yet, `Poll::Pending` is returned and
+    /// current task will be notified by a waker.
     pub fn poll_accept(
         mut self: Pin<&mut Self>,
         cx: &mut Context<'_>,

tokio/src/net/tcp/listener.rs

@@ -87,7 +87,7 @@ impl TcpListener {
         Err(last_err.unwrap_or_else(|| {
             io::Error::new(
                 io::ErrorKind::InvalidInput,
-                "could not resolve to any addresses",
+                "could not resolve to any address",
             )
         }))
     }
@@ -97,7 +97,7 @@ impl TcpListener {
         TcpListener::new(listener)
     }
 
-    /// Accept a new incoming connection from this listener.
+    /// Accepts a new incoming connection from this listener.
     ///
     /// This function will yield once a new TCP connection is established. When
     /// established, the corresponding [`TcpStream`] and the remote peer's
@@ -128,7 +128,10 @@ impl TcpListener {
         poll_fn(|cx| self.poll_accept(cx)).await
     }
 
-    #[doc(hidden)] // TODO: document
+    /// Attempts to poll `SocketAddr` and `TcpStream` bound to this address.
+    ///
+    /// In case if I/O resource isn't ready yet, `Poll::Pending` is returned and
+    /// current task will be notified by a waker.
     pub fn poll_accept(
         &mut self,
         cx: &mut Context<'_>,
@@ -157,7 +160,7 @@ impl TcpListener {
         }
     }
 
-    /// Create a new TCP listener from the standard library's TCP listener.
+    /// Creates a new TCP listener from the standard library's TCP listener.
     ///
     /// This method can be used when the `Handle::tcp_listen` method isn't
     /// sufficient because perhaps some more configuration is needed in terms of

tokio/src/net/tcp/stream.rs

@@ -91,12 +91,12 @@ impl TcpStream {
         Err(last_err.unwrap_or_else(|| {
             io::Error::new(
                 io::ErrorKind::InvalidInput,
-                "could not resolve to any addresses",
+                "could not resolve to any address",
             )
         }))
     }
 
-    /// Establish a connection to the specified `addr`.
+    /// Establishes a connection to the specified `addr`.
     async fn connect_addr(addr: SocketAddr) -> io::Result<TcpStream> {
         let sys = mio::net::TcpStream::connect(&addr)?;
         let stream = TcpStream::new(sys)?;
@@ -121,7 +121,7 @@ impl TcpStream {
         Ok(TcpStream { io })
     }
 
-    /// Create a new `TcpStream` from a `std::net::TcpStream`.
+    /// Creates new `TcpStream` from a `std::net::TcpStream`.
     ///
     /// This function will convert a TCP stream created by the standard library
     /// to a TCP stream ready to be used with the provided event loop handle.
@@ -161,7 +161,7 @@ impl TcpStream {
         Ok(TcpStream { io })
     }
 
-    // Connect a TcpStream asynchronously that may be built with a net2 TcpBuilder.
+    // Connects `TcpStream` asynchronously that may be built with a net2 `TcpBuilder`.
     //
     // This should be removed in favor of some in-crate TcpSocket builder API.
     #[doc(hidden)]
@@ -221,7 +221,7 @@ impl TcpStream {
         self.io.get_ref().peer_addr()
     }
 
-    /// Attempt to receive data on the socket, without removing that data from
+    /// Attempts to receive data on the socket, without removing that data from
     /// the queue, registering the current task for wakeup if data is not yet
     /// available.
     ///
@@ -629,7 +629,7 @@ impl TcpStream {
         self.io.get_ref().set_linger(dur)
     }
 
-    /// Split a `TcpStream` into a read half and a write half, which can be used
+    /// Splits a `TcpStream` into a read half and a write half, which can be used
     /// to read and write the stream concurrently.
     ///
     /// See the module level documenation of [`split`](super::split) for more

tokio/src/net/udp/socket.rs

@@ -33,7 +33,7 @@ impl UdpSocket {
         Err(last_err.unwrap_or_else(|| {
             io::Error::new(
                 io::ErrorKind::InvalidInput,
-                "could not resolve to any addresses",
+                "could not resolve to any address",
             )
         }))
     }
@@ -71,7 +71,7 @@ impl UdpSocket {
         Ok(UdpSocket { io })
     }
 
-    /// Split the `UdpSocket` into a receive half and a send half. The two parts
+    /// Splits the `UdpSocket` into a receive half and a send half. The two parts
     /// can be used to receive and send datagrams concurrently, even from two
     /// different tasks.
     ///
@@ -103,7 +103,7 @@ impl UdpSocket {
         Err(last_err.unwrap_or_else(|| {
             io::Error::new(
                 io::ErrorKind::InvalidInput,
-                "could not resolve to any addresses",
+                "could not resolve to any address",
             )
         }))
     }

tokio/src/net/unix/datagram.rs

@@ -193,7 +193,7 @@ impl UnixDatagram {
         self.io.get_ref().take_error()
     }
 
-    /// Shut down the read, write, or both halves of this connection.
+    /// Shuts down the read, write, or both halves of this connection.
     ///
     /// This function will cause all pending and future I/O calls on the
     /// specified portions to immediately return with an appropriate value

tokio/src/net/unix/incoming.rs

@@ -16,7 +16,12 @@ impl Incoming<'_> {
         Incoming { inner: listener }
     }
 
-    #[doc(hidden)] // TODO: dox
+    /// Attempts to poll `UnixStream` by polling inner `UnixListener` to accept
+    /// connection.
+    ///
+    /// If `UnixListener` isn't ready yet, `Poll::Pending` is returned and
+    /// current task will be notified by a waker.  Otherwise `Poll::Ready` with
+    /// `Result` containing `UnixStream` will be returned.
     pub fn poll_accept(
         mut self: Pin<&mut Self>,
         cx: &mut Context<'_>,

tokio/src/park/mod.rs

@@ -57,10 +57,10 @@ pub(crate) trait Park {
     /// Error returned by `park`
     type Error;
 
-    /// Get a new `Unpark` handle associated with this `Park` instance.
+    /// Gets a new `Unpark` handle associated with this `Park` instance.
     fn unpark(&self) -> Self::Unpark;
 
-    /// Block the current thread unless or until the token is available.
+    /// Blocks the current thread unless or until the token is available.
     ///
     /// A call to `park` does not guarantee that the thread will remain blocked
     /// forever, and callers should be prepared for this possibility. This
@@ -73,7 +73,7 @@ pub(crate) trait Park {
     /// `Park` implementation
     fn park(&mut self) -> Result<(), Self::Error>;
 
-    /// Park the current thread for at most `duration`.
+    /// Parks the current thread for at most `duration`.
     ///
     /// This function is the same as `park` but allows specifying a maximum time
     /// to block the thread for.
@@ -92,7 +92,7 @@ pub(crate) trait Park {
 
 /// Unblock a thread blocked by the associated `Park` instance.
 pub(crate) trait Unpark: Sync + Send + 'static {
-    /// Unblock a thread that is blocked by the associated `Park` handle.
+    /// Unblocks a thread that is blocked by the associated `Park` handle.
     ///
     /// Calling `unpark` atomically makes available the unpark token, if it is
     /// not already available.

tokio/src/process/kill.rs

@@ -2,7 +2,7 @@ use std::io;
 
 /// An interface for killing a running process.
 pub(crate) trait Kill {
-    /// Forcefully kill the process.
+    /// Forcefully kills the process.
     fn kill(&mut self) -> io::Result<()>;
 }
 

tokio/src/process/mod.rs

@@ -365,7 +365,7 @@ impl Command {
         self
     }
 
-    /// Configuration for the child process's standard input (stdin) handle.
+    /// Sets configuration for the child process's standard input (stdin) handle.
     ///
     /// Defaults to [`inherit`] when used with `spawn` or `status`, and
     /// defaults to [`piped`] when used with `output`.
@@ -389,7 +389,7 @@ impl Command {
         self
     }
 
-    /// Configuration for the child process's standard output (stdout) handle.
+    /// Sets configuration for the child process's standard output (stdout) handle.
     ///
     /// Defaults to [`inherit`] when used with `spawn` or `status`, and
     /// defaults to [`piped`] when used with `output`.
@@ -413,7 +413,7 @@ impl Command {
         self
     }
 
-    /// Configuration for the child process's standard error (stderr) handle.
+    /// Sets configuration for the child process's standard error (stderr) handle.
     ///
     /// Defaults to [`inherit`] when used with `spawn` or `status`, and
     /// defaults to [`piped`] when used with `output`.
@@ -468,7 +468,7 @@ impl Command {
         self
     }
 
-    /// Similar to `uid`, but sets the group ID of the child process. This has
+    /// Similar to `uid` but sets the group ID of the child process. This has
     /// the same semantics as the `uid` field.
     #[cfg(unix)]
     pub fn gid(&mut self, id: u32) -> &mut Command {
@@ -564,7 +564,7 @@ impl Command {
         })
     }
 
-    /// Executes a command as a child process, waiting for it to finish and
+    /// Executes the command as a child process, waiting for it to finish and
     /// collecting its exit status.
     ///
     /// By default, stdin, stdout and stderr are inherited from the parent.

tokio/src/process/unix/orphan.rs

@@ -22,9 +22,9 @@ impl<T: Wait> Wait for &mut T {
 
 /// An interface for queueing up an orphaned process so that it can be reaped.
 pub(crate) trait OrphanQueue<T> {
-    /// Add an orphan to the queue.
+    /// Adds an orphan to the queue.
     fn push_orphan(&self, orphan: T);
-    /// Attempt to reap every process in the queue, ignoring any errors and
+    /// Attempts to reap every process in the queue, ignoring any errors and
     /// enqueueing any orphans which have not yet exited.
     fn reap_orphans(&self);
 }

tokio/src/runtime/basic_scheduler.rs

@@ -77,7 +77,7 @@ where
         }
     }
 
-    /// Spawn a future onto the thread pool
+    /// Spawns a future onto the thread pool
     pub(crate) fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
     where
         F: Future + Send + 'static,
@@ -152,7 +152,7 @@ where
 }
 
 impl Spawner {
-    /// Spawn a future onto the thread pool
+    /// Spawns a future onto the thread pool
     pub(crate) fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
     where
         F: Future + Send + 'static,

tokio/src/runtime/blocking/shutdown.rs

@@ -25,7 +25,7 @@ pub(super) fn channel() -> (Sender, Receiver) {
 }
 
 impl Receiver {
-    /// Block the current thread until all `Sender` handles drop.
+    /// Blocks the current thread until all `Sender` handles drop.
     pub(crate) fn wait(&mut self) {
         use crate::runtime::enter::{enter, try_enter};
 

tokio/src/runtime/blocking/task.rs

@@ -8,7 +8,7 @@ pub(super) struct BlockingTask<T> {
 }
 
 impl<T> BlockingTask<T> {
-    /// Initialize a new blocking task from the given function
+    /// Initializes a new blocking task from the given function
     pub(super) fn new(func: T) -> BlockingTask<T> {
         BlockingTask { func: Some(func) }
     }

tokio/src/runtime/builder.rs

@@ -110,7 +110,7 @@ impl Builder {
         }
     }
 
-    /// Enable both I/O and time drivers.
+    /// Enables both I/O and time drivers.
     ///
     /// Doing this is a shorthand for calling `enable_io` and `enable_time`
     /// individually. If additional components are added to Tokio in the future,
@@ -136,7 +136,7 @@ impl Builder {
     }
 
     #[deprecated(note = "In future will be replaced by core_threads method")]
-    /// Set the maximum number of worker threads for the `Runtime`'s thread pool.
+    /// Sets the maximum number of worker threads for the `Runtime`'s thread pool.
     ///
     /// This must be a number between 1 and 32,768 though it is advised to keep
     /// this value on the smaller side.
@@ -147,7 +147,7 @@ impl Builder {
         self
     }
 
-    /// Set the core number of worker threads for the `Runtime`'s thread pool.
+    /// Sets the core number of worker threads for the `Runtime`'s thread pool.
     ///
     /// This should be a number between 1 and 32,768 though it is advised to keep
     /// this value on the smaller side.
@@ -192,7 +192,7 @@ impl Builder {
         self
     }
 
-    /// Set name of threads spawned by the `Runtime`'s thread pool.
+    /// Sets name of threads spawned by the `Runtime`'s thread pool.
     ///
     /// The default name is "tokio-runtime-worker".
     ///
@@ -212,7 +212,7 @@ impl Builder {
         self
     }
 
-    /// Set the stack size (in bytes) for worker threads.
+    /// Sets the stack size (in bytes) for worker threads.
     ///
     /// The actual stack size may be greater than this value if the platform
     /// specifies minimal stack size.
@@ -236,7 +236,7 @@ impl Builder {
         self
     }
 
-    /// Execute function `f` after each thread is started but before it starts
+    /// Executes function `f` after each thread is started but before it starts
     /// doing work.
     ///
     /// This is intended for bookkeeping and monitoring use cases.
@@ -263,7 +263,7 @@ impl Builder {
         self
     }
 
-    /// Execute function `f` before each thread stops.
+    /// Executes function `f` before each thread stops.
     ///
     /// This is intended for bookkeeping and monitoring use cases.
     ///
@@ -289,7 +289,7 @@ impl Builder {
         self
     }
 
-    /// Create the configured `Runtime`.
+    /// Creates the configured `Runtime`.
     ///
     /// The returned `ThreadPool` instance is ready to spawn tasks.
     ///
@@ -344,7 +344,7 @@ impl Builder {
 
 cfg_io_driver! {
     impl Builder {
-        /// Enable the I/O driver.
+        /// Enables the I/O driver.
         ///
         /// Doing this enables using net, process, signal, and some I/O types on
         /// the runtime.
@@ -368,7 +368,7 @@ cfg_io_driver! {
 
 cfg_time! {
     impl Builder {
-        /// Enable the time driver.
+        /// Enables the time driver.
         ///
         /// Doing this enables using `tokio::time` on the runtime.
         ///
@@ -391,7 +391,7 @@ cfg_time! {
 
 cfg_rt_core! {
     impl Builder {
-        /// Use a simpler scheduler that runs all tasks on the current-thread.
+        /// Sets runtime to use a simpler scheduler that runs all tasks on the current-thread.
         ///
         /// The executor and all necessary drivers will all be run on the current
         /// thread during `block_on` calls.
@@ -438,7 +438,7 @@ cfg_rt_core! {
 
 cfg_rt_threaded! {
     impl Builder {
-        /// Use a multi-threaded scheduler for executing tasks.
+        /// Sets runtime to use a multi-threaded scheduler for executing tasks.
         pub fn threaded_scheduler(&mut self) -> &mut Self {
             self.kind = Kind::ThreadPool;
             self

tokio/src/runtime/handle.rs

@@ -75,7 +75,7 @@ impl Handle {
 
 cfg_rt_core! {
     impl Handle {
-        /// Spawn a future onto the Tokio runtime.
+        /// Spawns a future onto the Tokio runtime.
         ///
         /// This spawns the given future onto the runtime's executor, usually a
         /// thread pool. The thread pool is then responsible for polling the future

tokio/src/runtime/park.rs

@@ -113,7 +113,7 @@ impl Unpark for Unparker {
 }
 
 impl Inner {
-    /// Park the current thread for at most `dur`.
+    /// Parks the current thread for at most `dur`.
     fn park(&self) {
         for _ in 0..3 {
             // If we were previously notified then we consume this notification and

tokio/src/runtime/thread_pool/mod.rs

@@ -72,7 +72,7 @@ impl ThreadPool {
         &self.spawner
     }
 
-    /// Spawn a task
+    /// Spawns a task
     pub(crate) fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
     where
         F: Future + Send + 'static,
@@ -81,7 +81,7 @@ impl ThreadPool {
         self.spawner.spawn(future)
     }
 
-    /// Block the current thread waiting for the future to complete.
+    /// Blocks the current thread waiting for the future to complete.
     ///
     /// The future will execute on the current thread, but all spawned tasks
     /// will be executed on the thread pool.

tokio/src/runtime/thread_pool/queue/global.rs

@@ -79,7 +79,7 @@ impl<T: 'static> Queue<T> {
         drop(self.pointers.lock().unwrap());
     }
 
-    /// Push a value into the queue and call the closure **while still holding
+    /// Pushes a value into the queue and call the closure **while still holding
     /// the push lock**
     pub(super) fn push<F>(&self, task: Task<T>, f: F)
     where

tokio/src/runtime/thread_pool/queue/inject.rs

@@ -11,7 +11,7 @@ impl<T: 'static> Inject<T> {
         Inject { cluster }
     }
 
-    /// Push a value onto the queue
+    /// Pushes a value onto the queue
     pub(crate) fn push<F>(&self, task: Task<T>, f: F)
     where
         F: FnOnce(Result<(), Task<T>>),
@@ -19,12 +19,12 @@ impl<T: 'static> Inject<T> {
         self.cluster.global.push(task, f)
     }
 
-    /// Check if the queue has been closed
+    /// Checks if the queue has been closed
     pub(crate) fn is_closed(&self) -> bool {
         self.cluster.global.is_closed()
     }
 
-    /// Close the queue
+    /// Closes the queue
     ///
     /// Returns `true` if the channel was closed. `false` indicates the pool was
     /// previously closed.
@@ -32,7 +32,7 @@ impl<T: 'static> Inject<T> {
         self.cluster.global.close()
     }
 
-    /// Wait for all locks on the queue to drop.
+    /// Waits for all locks on the queue to drop.
     ///
     /// This is done by locking w/o doing anything.
     pub(crate) fn wait_for_unlocked(&self) {

tokio/src/runtime/thread_pool/queue/local.rs

@@ -41,7 +41,7 @@ impl<T: 'static> Queue<T> {
 }
 
 impl<T> Queue<T> {
-    /// Push a task onto the local queue.
+    /// Pushes a task onto the local queue.
     ///
     /// This **must** be called by the producer thread.
     pub(super) unsafe fn push(&self, mut task: Task<T>, global: &global::Queue<T>) {
@@ -78,7 +78,7 @@ impl<T> Queue<T> {
         }
     }
 
-    /// Move a batch of tasks into the global queue.
+    /// Moves a batch of tasks into the global queue.
     ///
     /// This will temporarily make some of the tasks unavailable to stealers.
     /// Once `push_overflow` is done, a notification is sent out, so if other
@@ -148,7 +148,7 @@ impl<T> Queue<T> {
         Ok(())
     }
 
-    /// Pop a task from the local queue.
+    /// Pops a task from the local queue.
     ///
     /// This **must** be called by the producer thread
     pub(super) unsafe fn pop(&self) -> Option<Task<T>> {
@@ -193,7 +193,7 @@ impl<T> Queue<T> {
         head == tail
     }
 
-    /// Steal half the tasks from self and place them into `dst`.
+    /// Steals half the tasks from self and place them into `dst`.
     pub(super) unsafe fn steal(&self, dst: &Queue<T>) -> Option<Task<T>> {
         let dst_tail = dst.tail.unsync_load();
 

tokio/src/runtime/thread_pool/queue/worker.rs

@@ -30,7 +30,7 @@ impl<T: 'static> Worker<T> {
         self.cluster.global.is_closed()
     }
 
-    /// Push to the local queue.
+    /// Pushes to the local queue.
     ///
     /// If the local queue is full, the task is pushed onto the global queue.
     ///
@@ -58,17 +58,17 @@ impl<T: 'static> Worker<T> {
         unsafe { self.local().push(task, &self.cluster.global) }
     }
 
-    /// Pop a task checking the local queue first.
+    /// Pops a task checking the local queue first.
     pub(crate) fn pop_local_first(&self) -> Option<Task<T>> {
         self.local_pop().or_else(|| self.cluster.global.pop())
     }
 
-    /// Pop a task checking the global queue first.
+    /// Pops a task checking the global queue first.
     pub(crate) fn pop_global_first(&self) -> Option<Task<T>> {
         self.cluster.global.pop().or_else(|| self.local_pop())
     }
 
-    /// Steal from other local queues.
+    /// Steals from other local queues.
     ///
     /// `start` specifies the queue from which to start stealing.
     pub(crate) fn steal(&self, start: usize) -> Option<Task<T>> {

tokio/src/runtime/thread_pool/shutdown.rs

@@ -25,7 +25,7 @@ pub(super) fn channel() -> (Sender, Receiver) {
 }
 
 impl Receiver {
-    /// Block the current thread until all `Sender` handles drop.
+    /// Blocks the current thread until all `Sender` handles drop.
     pub(crate) fn wait(&mut self) {
         use crate::runtime::enter::{enter, try_enter};
 

tokio/src/runtime/thread_pool/slice.rs

@@ -30,7 +30,7 @@ unsafe impl Send for Set {}
 unsafe impl Sync for Set {}
 
 impl Set {
-    /// Create a new worker set using the provided queues.
+    /// Creates a new worker set using the provided queues.
     pub(crate) fn new(parkers: &[Parker]) -> Self {
         assert!(!parkers.is_empty());
 
@@ -115,7 +115,7 @@ impl Set {
         }
     }
 
-    /// Signal the pool is closed
+    /// Signals the pool is closed
     ///
     /// Returns `true` if the transition to closed is successful. `false`
     /// indicates the pool was already closed.
@@ -156,7 +156,7 @@ impl Set {
         &self.idle
     }
 
-    /// Wait for all locks on the injection queue to drop.
+    /// Waits for all locks on the injection queue to drop.
     ///
     /// This is done by locking w/o doing anything.
     pub(super) fn wait_for_unlocked(&self) {

tokio/src/runtime/thread_pool/spawner.rs

@@ -27,7 +27,7 @@ impl Spawner {
         Spawner { workers }
     }
 
-    /// Spawn a future onto the thread pool
+    /// Spawns a future onto the thread pool
     pub(crate) fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
     where
         F: Future + Send + 'static,

tokio/src/runtime/thread_pool/worker.rs

@@ -182,7 +182,7 @@ impl Worker {
         }
     }
 
-    /// Acquire the lock
+    /// Acquires the lock
     fn acquire_lock(&self) -> Option<GenerationGuard<'_>> {
         // Safety: Only getting `&self` access to access atomic field
         let owned = unsafe { &*self.slices.owned()[self.index].get() };
@@ -205,7 +205,7 @@ impl Worker {
         }
     }
 
-    /// Enter an in-place blocking section
+    /// Enters an in-place blocking section
     fn block_in_place(&self) {
         // If our Worker has already been given away, then blocking is fine!
         if self.gone.get() {
@@ -327,7 +327,7 @@ impl GenerationGuard<'_> {
         }
     }
 
-    /// Find local work
+    /// Finds local work
     fn find_local_work(&mut self) -> Option<Task<Shared>> {
         let tick = self.tick_fetch_inc();
 
@@ -527,7 +527,7 @@ impl GenerationGuard<'_> {
         }
     }
 
-    /// Shutdown the worker.
+    /// Shutdowns the worker.
     ///
     /// Once the shutdown flag has been observed, it is guaranteed that no
     /// further tasks may be pushed into the global queue.
@@ -573,7 +573,7 @@ impl GenerationGuard<'_> {
         }
     }
 
-    /// Increment the tick, returning the value from before the increment.
+    /// Increments the tick, returning the value from before the increment.
     fn tick_fetch_inc(&mut self) -> u16 {
         let tick = self.owned().tick.get();
         self.owned().tick.set(tick.wrapping_add(1));

tokio/src/signal/registry.rs

@@ -22,10 +22,10 @@ pub(crate) struct EventInfo {
 
 /// An interface for retrieving the `EventInfo` for a particular eventId.
 pub(crate) trait Storage {
-    /// Get the `EventInfo` for `id` if it exists.
+    /// Gets the `EventInfo` for `id` if it exists.
     fn event_info(&self, id: EventId) -> Option<&EventInfo>;
 
-    /// Invoke `f` once for each defined `EventInfo` in this storage.
+    /// Invokes `f` once for each defined `EventInfo` in this storage.
     fn for_each<'a, F>(&'a self, f: F)
     where
         F: FnMut(&'a EventInfo);
@@ -66,7 +66,7 @@ impl<S> Registry<S> {
 }
 
 impl<S: Storage> Registry<S> {
-    /// Register a new listener for `event_id`.
+    /// Registers a new listener for `event_id`.
     fn register_listener(&self, event_id: EventId, listener: Sender<()>) {
         self.storage
             .event_info(event_id)
@@ -77,7 +77,7 @@ impl<S: Storage> Registry<S> {
             .push(listener);
     }
 
-    /// Mark `event_id` as having been delivered, without broadcasting it to
+    /// Marks `event_id` as having been delivered, without broadcasting it to
     /// any listeners.
     fn record_event(&self, event_id: EventId) {
         if let Some(event_info) = self.storage.event_info(event_id) {
@@ -85,9 +85,9 @@ impl<S: Storage> Registry<S> {
         }
     }
 
-    /// Broadcast all previously recorded events to their respective listeners.
+    /// Broadcasts all previously recorded events to their respective listeners.
     ///
-    /// Returns true if an event was delivered to at least one listener.
+    /// Returns `true` if an event was delivered to at least one listener.
     fn broadcast(&self) -> bool {
         use crate::sync::mpsc::error::TrySendError;
 
@@ -136,20 +136,20 @@ impl ops::Deref for Globals {
 }
 
 impl Globals {
-    /// Register a new listener for `event_id`.
+    /// Registers a new listener for `event_id`.
     pub(crate) fn register_listener(&self, event_id: EventId, listener: Sender<()>) {
         self.registry.register_listener(event_id, listener);
     }
 
-    /// Mark `event_id` as having been delivered, without broadcasting it to
+    /// Marks `event_id` as having been delivered, without broadcasting it to
     /// any listeners.
     pub(crate) fn record_event(&self, event_id: EventId) {
         self.registry.record_event(event_id);
     }
 
-    /// Broadcast all previously recorded events to their respective listeners.
+    /// Broadcasts all previously recorded events to their respective listeners.
     ///
-    /// Returns true if an event was delivered to at least one listener.
+    /// Returns `true` if an event was delivered to at least one listener.
     pub(crate) fn broadcast(&self) -> bool {
         self.registry.broadcast()
     }

tokio/src/signal/unix.rs

@@ -214,7 +214,7 @@ fn action(globals: Pin<&'static Globals>, signal: c_int) {
     drop(sender.write(&[1]));
 }
 
-/// Enable this module to receive signal notifications for the `signal`
+/// Enables this module to receive signal notifications for the `signal`
 /// provided.
 ///
 /// This will register the signal handler if it hasn't already been registered,
@@ -243,7 +243,7 @@ fn signal_enable(signal: c_int) -> io::Result<()> {
     });
     registered?;
     // If the call_once failed, it won't be retried on the next attempt to register the signal. In
-    // such case it is not run, registered is still `Ok(())`, initialized is still false.
+    // such case it is not run, registered is still `Ok(())`, initialized is still `false`.
     if siginfo.initialized.load(Ordering::Relaxed) {
         Ok(())
     } else {
@@ -421,7 +421,7 @@ pub fn signal(kind: SignalKind) -> io::Result<Signal> {
 }
 
 impl Signal {
-    /// Receive the next signal notification event.
+    /// Receives the next signal notification event.
     ///
     /// `None` is returned if no more events can be received by this stream.
     ///
@@ -449,7 +449,7 @@ impl Signal {
         poll_fn(|cx| self.poll_recv(cx)).await
     }
 
-    /// Poll to receive the next signal notification event, outside of an
+    /// Polls to receive the next signal notification event, outside of an
     /// `async` context.
     ///
     /// `None` is returned if no more events can be received by this stream.

tokio/src/signal/windows.rs

@@ -149,7 +149,7 @@ pub struct CtrlBreak {
 }
 
 impl CtrlBreak {
-    /// Receive the next signal notification event.
+    /// Receives the next signal notification event.
     ///
     /// `None` is returned if no more events can be received by this stream.
     ///
@@ -175,7 +175,7 @@ impl CtrlBreak {
         poll_fn(|cx| self.poll_recv(cx)).await
     }
 
-    /// Poll to receive the next signal notification event, outside of an
+    /// Polls to receive the next signal notification event, outside of an
     /// `async` context.
     ///
     /// `None` is returned if no more events can be received by this stream.

tokio/src/sync/barrier.rs

@@ -126,7 +126,7 @@ impl Barrier {
 pub struct BarrierWaitResult(bool);
 
 impl BarrierWaitResult {
-    /// Returns true if this thread from wait is the "leader thread".
+    /// Returns `true` if this thread from wait is the "leader thread".
     ///
     /// Only one thread will have `true` returned from their result, all other threads will have
     /// `false` returned.

tokio/src/sync/broadcast.rs

@@ -301,7 +301,7 @@ struct Write<T> {
 /// Tracks a waiting receiver
 #[derive(Debug)]
 struct WaitNode {
-    /// True if queued
+    /// `true` if queued
     queued: AtomicBool,
 
     /// Task to wake when a permit is made available.
@@ -471,7 +471,7 @@ impl<T> Sender<T> {
             .map_err(|SendError(maybe_v)| SendError(maybe_v.unwrap()))
     }
 
-    /// Create a new [`Receiver`] handle that will receive values sent **after**
+    /// Creates a new [`Receiver`] handle that will receive values sent **after**
     /// this call to `subscribe`.
     ///
     /// # Examples
@@ -658,7 +658,7 @@ impl<T> Drop for Sender<T> {
 }
 
 impl<T> Receiver<T> {
-    /// Lock the next value if there is one.
+    /// Locks the next value if there is one.
     ///
     /// The caller is responsible for unlocking
     fn recv_ref(&mut self, spin: bool) -> Result<RecvGuard<'_, T>, TryRecvError> {
@@ -776,7 +776,7 @@ where
         }
     }
 
-    /// Receive the next value for this receiver.
+    /// Receives the next value for this receiver.
     ///
     /// Each [`Receiver`] handle will receive a clone of all values sent
     /// **after** it has subscribed.
@@ -946,7 +946,7 @@ impl<T> fmt::Debug for Receiver<T> {
 }
 
 impl<T> Slot<T> {
-    /// Try to lock the slot for a receiver. If `false`, then a sender holds the
+    /// Tries to lock the slot for a receiver. If `false`, then a sender holds the
     /// lock and the calling task will be notified once the sender has released
     /// the lock.
     fn try_rx_lock(&self) -> bool {

tokio/src/sync/mpsc/block.rs

@@ -107,7 +107,7 @@ impl<T> Block<T> {
         other_index.wrapping_sub(self.start_index) / BLOCK_CAP
     }
 
-    /// Read the value at the given offset.
+    /// Reads the value at the given offset.
     ///
     /// Returns `None` if the slot is empty.
     ///
@@ -135,7 +135,7 @@ impl<T> Block<T> {
         Some(Read::Value(value.assume_init()))
     }
 
-    /// Write a value to the block at the given offset.
+    /// Writes a value to the block at the given offset.
     ///
     /// # Safety
     ///
@@ -162,7 +162,7 @@ impl<T> Block<T> {
         self.ready_slots.fetch_or(TX_CLOSED, Release);
     }
 
-    /// Reset the block to a blank state. This enables reusing blocks in the
+    /// Resets the block to a blank state. This enables reusing blocks in the
     /// channel.
     ///
     /// # Safety
@@ -177,7 +177,7 @@ impl<T> Block<T> {
         self.ready_slots = AtomicUsize::new(0);
     }
 
-    /// Release the block to the rx half for freeing.
+    /// Releases the block to the rx half for freeing.
     ///
     /// This function is called by the tx half once it can be guaranteed that no
     /// more senders will attempt to access the block.
@@ -229,7 +229,7 @@ impl<T> Block<T> {
         }
     }
 
-    /// Load the next block
+    /// Loads the next block
     pub(crate) fn load_next(&self, ordering: Ordering) -> Option<NonNull<Block<T>>> {
         let ret = NonNull::new(self.next.load(ordering));
 
@@ -241,7 +241,7 @@ impl<T> Block<T> {
         ret
     }
 
-    /// Push `block` as the next block in the link.
+    /// Pushes `block` as the next block in the link.
     ///
     /// Returns Ok if successful, otherwise, a pointer to the next block in
     /// the list is returned.
@@ -274,7 +274,7 @@ impl<T> Block<T> {
         }
     }
 
-    /// Grow the `Block` linked list by allocating and appending a new block.
+    /// Grows the `Block` linked list by allocating and appending a new block.
     ///
     /// The next block in the linked list is returned. This may or may not be
     /// the one allocated by the function call.

tokio/src/sync/mpsc/bounded.rs

@@ -44,7 +44,7 @@ impl<T> fmt::Debug for Receiver<T> {
     }
 }
 
-/// Create a bounded mpsc channel for communicating between asynchronous tasks,
+/// Creates a bounded mpsc channel for communicating between asynchronous tasks,
 /// returning the sender/receiver halves.
 ///
 /// All data sent on `Sender` will become available on `Receiver` in the same
@@ -100,7 +100,7 @@ impl<T> Receiver<T> {
         Receiver { chan }
     }
 
-    /// Receive the next value for this receiver.
+    /// Receives the next value for this receiver.
     ///
     /// `None` is returned when all `Sender` halves have dropped, indicating
     /// that no further values can be sent on the channel.
@@ -263,7 +263,7 @@ impl<T> Sender<T> {
         Ok(())
     }
 
-    /// Send a value, waiting until there is capacity.
+    /// Sends a value, waiting until there is capacity.
     ///
     /// A successful send occurs when it is determined that the other end of the
     /// channel has not hung up already. An unsuccessful send would be one where

tokio/src/sync/mpsc/chan.rs

@@ -307,7 +307,7 @@ where
         })
     }
 
-    /// Receive the next value without blocking
+    /// Receives the next value without blocking
     pub(crate) fn try_recv(&mut self) -> Result<T, TryRecvError> {
         use super::block::Read::*;
         self.inner.rx_fields.with_mut(|rx_fields_ptr| {

tokio/src/sync/mpsc/list.rs

@@ -54,7 +54,7 @@ pub(crate) fn channel<T>() -> (Tx<T>, Rx<T>) {
 }
 
 impl<T> Tx<T> {
-    /// Push a value into the list.
+    /// Pushes a value into the list.
     pub(crate) fn push(&self, value: T) {
         // First, claim a slot for the value. `Acquire` is used here to
         // synchronize with the `fetch_add` in `reclaim_blocks`.
@@ -69,7 +69,7 @@ impl<T> Tx<T> {
         }
     }
 
-    /// Close the send half of the list
+    /// Closes the send half of the list
     ///
     /// Similar process as pushing a value, but instead of writing the value &
     /// setting the ready flag, the TX_CLOSED flag is set on the block.
@@ -220,7 +220,7 @@ impl<T> fmt::Debug for Tx<T> {
 }
 
 impl<T> Rx<T> {
-    /// Pop the next value off the queue
+    /// Pops the next value off the queue
     pub(crate) fn pop(&mut self, tx: &Tx<T>) -> Option<block::Read<T>> {
         // Advance `head`, if needed
         if !self.try_advancing_head() {
@@ -242,7 +242,7 @@ impl<T> Rx<T> {
         }
     }
 
-    /// Try advancing the block pointer to the block referenced by `self.index`.
+    /// Tries advancing the block pointer to the block referenced by `self.index`.
     ///
     /// Returns `true` if successful, `false` if there is no next block to load.
     fn try_advancing_head(&mut self) -> bool {

tokio/src/sync/mpsc/unbounded.rs

@@ -46,7 +46,7 @@ impl<T> fmt::Debug for UnboundedReceiver<T> {
     }
 }
 
-/// Create an unbounded mpsc channel for communicating between asynchronous
+/// Creates an unbounded mpsc channel for communicating between asynchronous
 /// tasks.
 ///
 /// A `send` on this channel will always succeed as long as the receive half has
@@ -78,7 +78,7 @@ impl<T> UnboundedReceiver<T> {
         self.chan.recv(cx)
     }
 
-    /// Receive the next value for this receiver.
+    /// Receives the next value for this receiver.
     ///
     /// `None` is returned when all `Sender` halves have dropped, indicating
     /// that no further values can be sent on the channel.

tokio/src/sync/mutex.rs

@@ -166,7 +166,7 @@ impl<T> Mutex<T> {
         guard
     }
 
-    /// Try to acquire the lock
+    /// Tries to acquire the lock
     pub fn try_lock(&self) -> Result<MutexGuard<'_, T>, TryLockError> {
         let mut permit = semaphore::Permit::new();
         match permit.try_acquire(1, &self.s) {

tokio/src/sync/oneshot.rs

@@ -237,7 +237,7 @@ impl<T> Sender<T> {
         Pending
     }
 
-    /// Wait for the associated [`Receiver`] handle to close.
+    /// Waits for the associated [`Receiver`] handle to close.
     ///
     /// A [`Receiver`] is closed by either calling [`close`] explicitly or the
     /// [`Receiver`] value is dropped.
@@ -354,7 +354,7 @@ impl<T> Drop for Sender<T> {
 }
 
 impl<T> Receiver<T> {
-    /// Prevent the associated [`Sender`] handle from sending a value.
+    /// Prevents the associated [`Sender`] handle from sending a value.
     ///
     /// Any `send` operation which happens after calling `close` is guaranteed
     /// to fail. After calling `close`, `Receiver::poll`] should be called to
@@ -610,7 +610,7 @@ impl<T> Inner<T> {
         }
     }
 
-    /// Consume the value. This function does not check `state`.
+    /// Consumes the value. This function does not check `state`.
     unsafe fn consume_value(&self) -> Option<T> {
         self.value.with_mut(|ptr| (*ptr).take())
     }

tokio/src/sync/semaphore.rs

@@ -49,12 +49,12 @@ impl Semaphore {
         self.ll_sem.available_permits()
     }
 
-    /// Add `n` new permits to the semaphore.
+    /// Adds `n` new permits to the semaphore.
     pub fn add_permits(&self, n: usize) {
         self.ll_sem.add_permits(n);
     }
 
-    /// Acquire permit from the semaphore
+    /// Acquires permit from the semaphore
     pub async fn acquire(&self) -> SemaphorePermit<'_> {
         let mut permit = SemaphorePermit {
             sem: &self,
@@ -66,7 +66,7 @@ impl Semaphore {
         permit
     }
 
-    /// Try to acquire a permit form the semaphore
+    /// Tries to acquire a permit form the semaphore
     pub fn try_acquire(&self) -> Result<SemaphorePermit<'_>, TryAcquireError> {
         let mut ll_permit = ll::Permit::new();
         match ll_permit.try_acquire(1, &self.ll_sem) {
@@ -80,7 +80,7 @@ impl Semaphore {
 }
 
 impl<'a> SemaphorePermit<'a> {
-    /// Forget the permit **without** releasing it back to the semaphore.
+    /// Forgets the permit **without** releasing it back to the semaphore.
     /// This can be used to reduce the amount of permits available from a
     /// semaphore.
     pub fn forget(mut self) {

tokio/src/sync/semaphore_ll.rs

@@ -177,7 +177,7 @@ impl Semaphore {
         curr.available_permits()
     }
 
-    /// Try to acquire the requested number of permits, registering the waiter
+    /// Tries to acquire the requested number of permits, registering the waiter
     /// if not enough permits are available.
     fn poll_acquire(
         &self,
@@ -201,7 +201,7 @@ impl Semaphore {
         }
     }
 
-    /// Poll for a permit
+    /// Polls for a permit
     ///
     /// Tries to acquire available permits first. If unable to acquire a
     /// sufficient number of permits, the caller's waiter is pushed onto the
@@ -319,7 +319,7 @@ impl Semaphore {
         }
     }
 
-    /// Close the semaphore. This prevents the semaphore from issuing new
+    /// Closes the semaphore. This prevents the semaphore from issuing new
     /// permits and notifies all pending waiters.
     pub(crate) fn close(&self) {
         // Acquire the `rx_lock`, setting the "closed" flag on the lock.
@@ -334,7 +334,7 @@ impl Semaphore {
         self.add_permits_locked(0, true);
     }
 
-    /// Add `n` new permits to the semaphore.
+    /// Adds `n` new permits to the semaphore.
     pub(crate) fn add_permits(&self, n: usize) {
         if n == 0 {
             return;
@@ -378,7 +378,7 @@ impl Semaphore {
         }
     }
 
-    /// Release a specific amount of permits to the semaphore
+    /// Releases a specific amount of permits to the semaphore
     ///
     /// This function is called by `add_permits` after the add lock has been
     /// acquired.
@@ -597,7 +597,7 @@ unsafe impl Sync for Semaphore {}
 // ===== impl Permit =====
 
 impl Permit {
-    /// Create a new `Permit`.
+    /// Creates a new `Permit`.
     ///
     /// The permit begins in the "unacquired" state.
     pub(crate) fn new() -> Permit {
@@ -609,7 +609,7 @@ impl Permit {
         }
     }
 
-    /// Returns true if the permit has been acquired
+    /// Returns `true` if the permit has been acquired
     pub(crate) fn is_acquired(&self) -> bool {
         match self.state {
             PermitState::Acquired(num) if num > 0 => true,
@@ -617,7 +617,7 @@ impl Permit {
         }
     }
 
-    /// Try to acquire the permit. If no permits are available, the current task
+    /// Tries to acquire the permit. If no permits are available, the current task
     /// is notified once a new permit becomes available.
     pub(crate) fn poll_acquire(
         &mut self,
@@ -693,7 +693,7 @@ impl Permit {
         }
     }
 
-    /// Try to acquire the permit.
+    /// Tries to acquire the permit.
     pub(crate) fn try_acquire(
         &mut self,
         num_permits: u16,
@@ -739,13 +739,13 @@ impl Permit {
         }
     }
 
-    /// Release a permit back to the semaphore
+    /// Releases a permit back to the semaphore
     pub(crate) fn release(&mut self, n: u16, semaphore: &Semaphore) {
         let n = self.forget(n);
         semaphore.add_permits(n as usize);
     }
 
-    /// Forget the permit **without** releasing it back to the semaphore.
+    /// Forgets the permit **without** releasing it back to the semaphore.
     ///
     /// After calling `forget`, `poll_acquire` is able to acquire new permit
     /// from the sempahore.
@@ -831,7 +831,7 @@ impl std::error::Error for AcquireError {}
 // ===== impl TryAcquireError =====
 
 impl TryAcquireError {
-    /// Returns true if the error was caused by a closed semaphore.
+    /// Returns `true` if the error was caused by a closed semaphore.
     pub(crate) fn is_closed(&self) -> bool {
         match self {
             TryAcquireError::Closed => true,
@@ -839,7 +839,7 @@ impl TryAcquireError {
         }
     }
 
-    /// Returns true if the error was caused by calling `try_acquire` on a
+    /// Returns `true` if the error was caused by calling `try_acquire` on a
     /// semaphore with no available permits.
     pub(crate) fn is_no_permits(&self) -> bool {
         match self {
@@ -1061,7 +1061,7 @@ impl SemState {
         self.0 >> NUM_SHIFT
     }
 
-    /// Returns true if the state has permits that can be claimed by a waiter.
+    /// Returns `true` if the state has permits that can be claimed by a waiter.
     fn has_available_permits(self) -> bool {
         self.0 & NUM_FLAG == NUM_FLAG
     }
@@ -1070,7 +1070,7 @@ impl SemState {
         !self.has_available_permits() && !self.is_stub(stub)
     }
 
-    /// Try to atomically acquire specified number of permits.
+    /// Tries to atomically acquire specified number of permits.
     ///
     /// # Return
     ///
@@ -1096,7 +1096,7 @@ impl SemState {
         true
     }
 
-    /// Release permits
+    /// Releases permits
     ///
     /// Returns `true` if the permits were accepted.
     fn release_permits(&mut self, permits: usize, stub: &Waiter) {
@@ -1132,7 +1132,7 @@ impl SemState {
         (self.0 & !CLOSED_FLAG) as *mut Waiter
     }
 
-    /// Set to a pointer to a waiter.
+    /// Sets to a pointer to a waiter.
     ///
     /// This can only be done from the full state.
     fn set_waiter(&mut self, waiter: NonNull<Waiter>) {
@@ -1146,7 +1146,7 @@ impl SemState {
         self.as_ptr() as usize == stub as *const _ as usize
     }
 
-    /// Load the state from an AtomicUsize.
+    /// Loads the state from an AtomicUsize.
     fn load(cell: &AtomicUsize, ordering: Ordering) -> SemState {
         let value = cell.load(ordering);
         SemState(value)

tokio/src/sync/watch.rs

@@ -151,7 +151,7 @@ struct WatchInner {
 
 const CLOSED: usize = 1;
 
-/// Create a new watch channel, returning the "send" and "receive" handles.
+/// Creates a new watch channel, returning the "send" and "receive" handles.
 ///
 /// All values sent by [`Sender`] will become visible to the [`Receiver`] handles.
 /// Only the last value sent is made available to the [`Receiver`] half. All
@@ -320,7 +320,7 @@ impl WatchInner {
 }
 
 impl<T> Sender<T> {
-    /// Broadcast a new value via the channel, notifying all receivers.
+    /// Broadcasts a new value via the channel, notifying all receivers.
     pub fn broadcast(&self, value: T) -> Result<(), error::SendError<T>> {
         let shared = match self.shared.upgrade() {
             Some(shared) => shared,
@@ -363,7 +363,7 @@ impl<T> Sender<T> {
     }
 }
 
-/// Notify all watchers of a change
+/// Notifies all watchers of a change
 fn notify_all<T>(shared: &Shared<T>) {
     let watchers = shared.watchers.lock().unwrap();
 

tokio/src/task/blocking.rs

@@ -1,7 +1,7 @@
 use crate::task::JoinHandle;
 
 cfg_rt_threaded! {
-    /// Run the provided blocking function without blocking the executor.
+    /// Runs the provided blocking function without blocking the executor.
     ///
     /// In general, issuing a blocking call or performing a lot of compute in a
     /// future without yielding is not okay, as it may prevent the executor from
@@ -39,7 +39,7 @@ cfg_rt_threaded! {
 }
 
 cfg_blocking! {
-    /// Run the provided closure on a thread where blocking is acceptable.
+    /// Runs the provided closure on a thread where blocking is acceptable.
     ///
     /// In general, issuing a blocking call or performing a lot of compute in a future without
     /// yielding is not okay, as it may prevent the executor from driving other futures forward.

tokio/src/task/core.rs

@@ -75,7 +75,7 @@ enum Stage<T: Future> {
 }
 
 impl<T: Future> Cell<T> {
-    /// Allocate a new task cell, containing the header, trailer, and core
+    /// Allocates a new task cell, containing the header, trailer, and core
     /// structures.
     pub(super) fn new<S>(future: T, state: State) -> Box<Cell<T>>
     where

tokio/src/task/harness.rs

@@ -48,7 +48,7 @@ where
     T: Future,
     S: Schedule,
 {
-    /// Poll the inner future.
+    /// Polls the inner future.
     ///
     /// All necessary state checks and transitions are performed.
     ///
@@ -450,7 +450,7 @@ where
         }
     }
 
-    /// Return `true` if the task structure should be deallocated
+    /// Returns `true` if the task structure should be deallocated
     fn transition_to_complete(&mut self, join_interest: bool) -> Snapshot {
         let res = self.header().state.transition_to_complete();
 
@@ -461,7 +461,7 @@ where
         res
     }
 
-    /// Return `true` if the task structure should be deallocated
+    /// Returns `true` if the task structure should be deallocated
     fn transition_to_released(&mut self, join_interest: bool) -> Snapshot {
         if join_interest {
             let res1 = self.transition_to_complete(join_interest);

tokio/src/task/local.rs

@@ -252,7 +252,7 @@ impl LocalSet {
         handle
     }
 
-    /// Run a future to completion on the provided runtime, driving any local
+    /// Runs a future to completion on the provided runtime, driving any local
     /// futures spawned on this task set on the current thread.
     ///
     /// This runs the given future on the runtime, blocking until it is
@@ -405,7 +405,7 @@ impl<F: Future> Future for LocalFuture<F> {
             }
 
             if scheduler.tick() {
-                // If `tick` returns true, we need to notify the local future again:
+                // If `tick` returns `true`, we need to notify the local future again:
                 // there are still tasks remaining in the run queue.
                 cx.waker().wake_by_ref();
             }

tokio/src/task/queue.rs

@@ -49,7 +49,7 @@ pub(crate) struct RemoteQueue<S: 'static> {
     /// FIFO list of tasks
     queue: VecDeque<Task<S>>,
 
-    /// `true` when a task can be pushed into the queue, false otherwise.
+    /// `true` when a task can be pushed into the queue, `false` otherwise.
     open: bool,
 }
 
@@ -76,7 +76,7 @@ where
         }
     }
 
-    /// Add a new task to the scheduler.
+    /// Adds a new task to the scheduler.
     ///
     /// # Safety
     ///
@@ -85,7 +85,7 @@ where
         (*self.owned_tasks.get()).insert(task);
     }
 
-    /// Push a task to the local queue.
+    /// Pushes a task to the local queue.
     ///
     /// # Safety
     ///
@@ -94,7 +94,7 @@ where
         (*self.local_queue.get()).push_back(task);
     }
 
-    /// Remove a task from the local queue.
+    /// Removes a task from the local queue.
     ///
     /// # Safety
     ///
@@ -103,7 +103,7 @@ where
         (*self.owned_tasks.get()).remove(task);
     }
 
-    /// Lock the remote queue, returning a `MutexGuard`.
+    /// Locks the remote queue, returning a `MutexGuard`.
     ///
     /// This can be used to push to the remote queue and perform other
     /// operations while holding the lock.
@@ -117,7 +117,7 @@ where
             .expect("failed to lock remote queue")
     }
 
-    /// Release a task from outside of the thread that owns the scheduler.
+    /// Releases a task from outside of the thread that owns the scheduler.
     ///
     /// This simply pushes the task to the pending drop queue.
     pub(crate) fn release_remote(&self, task: Task<S>) {
@@ -173,7 +173,7 @@ where
         lock.queue.pop_front()
     }
 
-    /// Returns true if any owned tasks are still bound to this scheduler.
+    /// Returns `true` if any owned tasks are still bound to this scheduler.
     ///
     /// # Safety
     ///
@@ -182,7 +182,7 @@ where
         !(*self.owned_tasks.get()).is_empty()
     }
 
-    /// Drain any tasks that have previously been released from other threads.
+    /// Drains any tasks that have previously been released from other threads.
     ///
     /// # Safety
     ///
@@ -194,7 +194,7 @@ where
         }
     }
 
-    /// Shut down the queues.
+    /// Shuts down the queues.
     ///
     /// This performs the following operations:
     ///
@@ -233,7 +233,7 @@ where
         self.drain_pending_drop();
     }
 
-    /// Drain both the local and remote run queues, shutting down any tasks.
+    /// Drains both the local and remote run queues, shutting down any tasks.
     ///
     /// # Safety
     ///
@@ -243,7 +243,7 @@ where
         self.close_remote();
     }
 
-    /// Shut down the scheduler's owned task list.
+    /// Shuts down the scheduler's owned task list.
     ///
     /// # Safety
     ///
@@ -252,7 +252,7 @@ where
         (*self.owned_tasks.get()).shutdown();
     }
 
-    /// Drain the remote queue, and shut down its tasks.
+    /// Drains the remote queue, and shut down its tasks.
     ///
     /// This closes the remote queue. Any additional tasks added to it will be
     /// shut down instead.
@@ -284,7 +284,7 @@ where
         }
     }
 
-    /// Drain the local queue, and shut down its tasks.
+    /// Drains the local queue, and shut down its tasks.
     ///
     /// # Safety
     ///

tokio/src/task/state.rs

@@ -64,12 +64,12 @@ impl State {
         }
     }
 
-    /// Load the current state, establishes `Acquire` ordering.
+    /// Loads the current state, establishes `Acquire` ordering.
     pub(super) fn load(&self) -> Snapshot {
         Snapshot(self.val.load(Acquire))
     }
 
-    /// Transition a task to the `Running` state.
+    /// Transitions a task to the `Running` state.
     ///
     /// Returns a snapshot of the state **after** the transition.
     pub(super) fn transition_to_running(&self) -> Snapshot {
@@ -96,7 +96,7 @@ impl State {
         next
     }
 
-    /// Transition the task from `Running` -> `Idle`.
+    /// Transitions the task from `Running` -> `Idle`.
     ///
     /// Returns a snapshot of the state **after** the transition.
     pub(super) fn transition_to_idle(&self) -> Snapshot {
@@ -119,7 +119,7 @@ impl State {
         next
     }
 
-    /// Transition the task from `Running` -> `Complete`.
+    /// Transitions the task from `Running` -> `Complete`.
     ///
     /// Returns a snapshot of the state **after** the transition.
     pub(super) fn transition_to_complete(&self) -> Snapshot {
@@ -136,7 +136,7 @@ impl State {
         next
     }
 
-    /// Transition the task from `Running` -> `Released`.
+    /// Transitions the task from `Running` -> `Released`.
     ///
     /// Returns a snapshot of the state **after** the transition.
     pub(super) fn transition_to_released(&self) -> Snapshot {
@@ -157,7 +157,7 @@ impl State {
         next
     }
 
-    /// Transition the task to the canceled state.
+    /// Transitions the task to the canceled state.
     ///
     /// Returns the snapshot of the state **after** the transition **if** the
     /// transition was made successfully
@@ -212,7 +212,7 @@ impl State {
         }
     }
 
-    /// Final transition to `Released`. Called when primary task handle is
+    /// Transitions to `Released`. Called when primary task handle is
     /// dropped. This is roughly a "ref decrement" operation.
     ///
     /// Returns a snapshot of the state **after** the transition.
@@ -239,7 +239,7 @@ impl State {
         next
     }
 
-    /// Transition the state to `Scheduled`.
+    /// Transitions the state to `Scheduled`.
     ///
     /// Returns `true` if the task needs to be submitted to the pool for
     /// execution
@@ -250,7 +250,7 @@ impl State {
         prev & MASK == 0
     }
 
-    /// Optimistically try to swap the state assuming the join handle is
+    /// Optimistically tries to swap the state assuming the join handle is
     /// __immediately__ dropped on spawn
     pub(super) fn drop_join_handle_fast(&self) -> bool {
         use std::sync::atomic::Ordering::Relaxed;
@@ -272,7 +272,7 @@ impl State {
             .is_ok()
     }
 
-    /// The join handle has completed by reading the output
+    /// The join handle has completed by reading the output.
     ///
     /// Returns a snapshot of the state **after** the transition.
     pub(super) fn complete_join_handle(&self) -> Snapshot {
@@ -328,7 +328,7 @@ impl State {
         }
     }
 
-    /// Store the join waker.
+    /// Stores the join waker.
     pub(super) fn store_join_waker(&self) -> Snapshot {
         use crate::loom::sync::atomic;
 

tokio/src/task/yield_now.rs

@@ -3,14 +3,13 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 
 doc_rt_core! {
-    /// Return a `Future` that can be `await`-ed to yield execution back to the
-    /// Tokio runtime.
+    /// Yields execution back to the Tokio runtime.
     ///
-    /// A task yields by awaiting the returned `Future`, and may resume when
-    /// that future completes (with no output.) The current task will be
-    /// re-added as a pending task at the _back_ of the pending queue. Any
-    /// other pending tasks will be scheduled. No other waking is required for
-    /// the task to continue.
+    /// A task yields by awaiting on `yield_now()`, and may resume when that
+    /// future completes (with no output.) The current task will be re-added as
+    /// a pending task at the _back_ of the pending queue. Any other pending
+    /// tasks will be scheduled. No other waking is required for the task to
+    /// continue.
     ///
     /// See also the usage example in the [task module](index.html#yield_now).
     #[must_use = "yield_now does nothing unless polled/`await`-ed"]

tokio/src/time/delay.rs

@@ -5,7 +5,7 @@ use std::future::Future;
 use std::pin::Pin;
 use std::task::{self, Poll};
 
-/// Wait until `deadline` is reached.
+/// Waits until `deadline` is reached.
 ///
 /// No work is performed while awaiting on the delay to complete. The delay
 /// operates at millisecond granularity and should not be used for tasks that
@@ -20,7 +20,7 @@ pub fn delay_until(deadline: Instant) -> Delay {
     Delay { registration }
 }
 
-/// Wait until `duration` has elapsed.
+/// Waits until `duration` has elapsed.
 ///
 /// Equivalent to `delay_until(Instant::now() + duration)`. An asynchronous
 /// analog to `std::thread::sleep`.
@@ -59,14 +59,14 @@ impl Delay {
         self.registration.deadline()
     }
 
-    /// Returns true if the `Delay` has elapsed
+    /// Returns `true` if the `Delay` has elapsed
     ///
     /// A `Delay` is elapsed when the requested duration has elapsed.
     pub fn is_elapsed(&self) -> bool {
         self.registration.is_elapsed()
     }
 
-    /// Reset the `Delay` instance to a new deadline.
+    /// Resets the `Delay` instance to a new deadline.
     ///
     /// Calling this function allows changing the instant at which the `Delay`
     /// future completes without having to create new associated state.

tokio/src/time/delay_queue.rs

@@ -28,7 +28,7 @@ use std::task::{self, Poll};
 ///
 /// Once delays have been configured, the `DelayQueue` is used via its
 /// [`Stream`] implementation. [`poll`] is called. If an entry has reached its
-/// deadline, it is returned. If not, `Async::NotReady` indicating that the
+/// deadline, it is returned. If not, `Poll::Pending` indicating that the
 /// current task will be notified once the deadline has been reached.
 ///
 /// # `Stream` implementation
@@ -203,7 +203,7 @@ struct Data<T> {
 const MAX_ENTRIES: usize = (1 << 30) - 1;
 
 impl<T> DelayQueue<T> {
-    /// Create a new, empty, `DelayQueue`
+    /// Creates a new, empty, `DelayQueue`
     ///
     /// The queue will not allocate storage until items are inserted into it.
     ///
@@ -217,7 +217,7 @@ impl<T> DelayQueue<T> {
         DelayQueue::with_capacity(0)
     }
 
-    /// Create a new, empty, `DelayQueue` with the specified capacity.
+    /// Creates a new, empty, `DelayQueue` with the specified capacity.
     ///
     /// The queue will be able to hold at least `capacity` elements without
     /// reallocating. If `capacity` is 0, the queue will not allocate for
@@ -253,7 +253,7 @@ impl<T> DelayQueue<T> {
         }
     }
 
-    /// Insert `value` into the queue set to expire at a specific instant in
+    /// Inserts `value` into the queue set to expire at a specific instant in
     /// time.
     ///
     /// This function is identical to `insert`, but takes an `Instant` instead
@@ -332,7 +332,7 @@ impl<T> DelayQueue<T> {
         Key::new(key)
     }
 
-    /// Attempt to pull out the next value of the delay queue, registering the
+    /// Attempts to pull out the next value of the delay queue, registering the
     /// current task for wakeup if the value is not yet available, and returning
     /// None if the queue is exhausted.
     pub fn poll_expired(
@@ -355,7 +355,7 @@ impl<T> DelayQueue<T> {
         }))
     }
 
-    /// Insert `value` into the queue set to expire after the requested duration
+    /// Inserts `value` into the queue set to expire after the requested duration
     /// elapses.
     ///
     /// This function is identical to `insert_at`, but takes a `Duration`
@@ -422,7 +422,7 @@ impl<T> DelayQueue<T> {
         }
     }
 
-    /// Remove the item associated with `key` from the queue.
+    /// Removes the item associated with `key` from the queue.
     ///
     /// There must be an item associated with `key`. The function returns the
     /// removed item as well as the `Instant` at which it will the delay will
@@ -631,7 +631,7 @@ impl<T> DelayQueue<T> {
         self.slab.len()
     }
 
-    /// Reserve capacity for at least `additional` more items to be queued
+    /// Reserves capacity for at least `additional` more items to be queued
     /// without allocating.
     ///
     /// `reserve` does nothing if the queue already has sufficient capacity for

tokio/src/time/driver/atomic_stack.rs

@@ -29,7 +29,7 @@ impl AtomicStack {
         }
     }
 
-    /// Push an entry onto the stack.
+    /// Pushes an entry onto the stack.
     ///
     /// Returns `true` if the entry was pushed, `false` if the entry is already
     /// on the stack, `Err` if the timer is shutdown.
@@ -72,13 +72,13 @@ impl AtomicStack {
         Ok(true)
     }
 
-    /// Take all entries from the stack
+    /// Takes all entries from the stack
     pub(crate) fn take(&self) -> AtomicStackEntries {
         let ptr = self.head.swap(ptr::null_mut(), SeqCst);
         AtomicStackEntries { ptr }
     }
 
-    /// Drain all remaining nodes in the stack and prevent any new nodes from
+    /// Drains all remaining nodes in the stack and prevent any new nodes from
     /// being pushed onto the stack.
     pub(crate) fn shutdown(&self) {
         // Shutdown the processing queue

tokio/src/time/driver/handle.rs

@@ -10,12 +10,12 @@ pub(crate) struct Handle {
 }
 
 impl Handle {
-    /// Create a new timer `Handle` from a shared `Inner` timer state.
+    /// Creates a new timer `Handle` from a shared `Inner` timer state.
     pub(crate) fn new(inner: Weak<Inner>) -> Self {
         Handle { inner }
     }
 
-    /// Try to get a handle to the current timer.
+    /// Tries to get a handle to the current timer.
     ///
     /// # Panics
     ///
@@ -24,7 +24,7 @@ impl Handle {
         context::time_handle().expect("no current timer")
     }
 
-    /// Try to return a strong ref to the inner
+    /// Tries to return a strong ref to the inner
     pub(crate) fn inner(&self) -> Option<Arc<Inner>> {
         self.inner.upgrade()
     }

tokio/src/time/driver/mod.rs

@@ -117,7 +117,7 @@ impl<T> Driver<T>
 where
     T: Park,
 {
-    /// Create a new `Driver` instance that uses `park` to block the current
+    /// Creates a new `Driver` instance that uses `park` to block the current
     /// thread and `now` to get the current `Instant`.
     ///
     /// Specifying the source of time is useful when testing.
@@ -147,7 +147,7 @@ where
         self.inner.start + Duration::from_millis(when)
     }
 
-    /// Run timer related logic
+    /// Runs timer related logic
     fn process(&mut self) {
         let now = crate::time::ms(
             self.clock.now() - self.inner.start,
@@ -169,7 +169,7 @@ where
         self.inner.elapsed.store(self.wheel.elapsed(), SeqCst);
     }
 
-    /// Process the entry queue
+    /// Processes the entry queue
     ///
     /// This handles adding and canceling timeouts.
     fn process_queue(&mut self) {
@@ -199,7 +199,7 @@ where
         entry.set_when_internal(None);
     }
 
-    /// Fire the entry if it needs to, otherwise queue it to be processed later.
+    /// Fires the entry if it needs to, otherwise queue it to be processed later.
     ///
     /// Returns `None` if the entry was fired.
     fn add_entry(&mut self, entry: Arc<Entry>, when: u64) {
@@ -333,7 +333,7 @@ impl Inner {
         self.elapsed.load(SeqCst)
     }
 
-    /// Increment the number of active timeouts
+    /// Increments the number of active timeouts
     fn increment(&self) -> Result<(), Error> {
         let mut curr = self.num.load(SeqCst);
 
@@ -352,7 +352,7 @@ impl Inner {
         }
     }
 
-    /// Decrement the number of active timeouts
+    /// Decrements the number of active timeouts
     fn decrement(&self) {
         let prev = self.num.fetch_sub(1, SeqCst);
         debug_assert!(prev <= MAX_TIMEOUTS);

tokio/src/time/driver/stack.rs

@@ -55,7 +55,7 @@ impl wheel::Stack for Stack {
         self.head = Some(entry);
     }
 
-    /// Pop an item from the stack
+    /// Pops an item from the stack
     fn pop(&mut self, _: &mut ()) -> Option<Arc<Entry>> {
         let entry = self.head.take();
 

tokio/src/time/error.rs

@@ -31,7 +31,7 @@ enum Kind {
 }
 
 impl Error {
-    /// Create an error representing a shutdown timer.
+    /// Creates an error representing a shutdown timer.
     pub fn shutdown() -> Error {
         Error(Shutdown)
     }
@@ -44,7 +44,7 @@ impl Error {
         }
     }
 
-    /// Create an error representing a timer at capacity.
+    /// Creates an error representing a timer at capacity.
     pub fn at_capacity() -> Error {
         Error(AtCapacity)
     }

tokio/src/time/throttle.rs

@@ -10,7 +10,7 @@ use std::task::{self, Poll};
 
 use pin_project_lite::pin_project;
 
-/// Slow down a stream by enforcing a delay between items.
+/// Slows down a stream by enforcing a delay between items.
 /// They will be produced not more often than the specified interval.
 ///
 /// # Example