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

81 files changed, 277 insertions, 266 deletions

diff --git a/tokio/src/fs/create_dir_all.rs b/tokio/src/fs/create_dir_all.rs
index 7d89280d..21f0c82d 100644
--- a/tokio/src/fs/create_dir_all.rs
+++ b/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]
diff --git a/tokio/src/fs/file.rs b/tokio/src/fs/file.rs
index 9110831a..a1f22fc9 100644
--- a/tokio/src/fs/file.rs
+++ b/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
     ///
diff --git a/tokio/src/fs/metadata.rs b/tokio/src/fs/metadata.rs
index 6bbb44ad..ff9cded7 100644
--- a/tokio/src/fs/metadata.rs
+++ b/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]
diff --git a/tokio/src/fs/read.rs b/tokio/src/fs/read.rs
index f61275d0..2d80eb5b 100644
--- a/tokio/src/fs/read.rs
+++ b/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]
 ///
diff --git a/tokio/src/fs/read_dir.rs b/tokio/src/fs/read_dir.rs
index 06eed384..fbc006df 100644
--- a/tokio/src/fs/read_dir.rs
+++ b/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.
diff --git a/tokio/src/fs/rename.rs b/tokio/src/fs/rename.rs
index de647da9..4f980821 100644
--- a/tokio/src/fs/rename.rs
+++ b/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.
diff --git a/tokio/src/future/maybe_done.rs b/tokio/src/future/maybe_done.rs
index 94b829f2..e93af521 100644
--- a/tokio/src/future/maybe_done.rs
+++ b/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> {
diff --git a/tokio/src/future/ready.rs b/tokio/src/future/ready.rs
index ba5d4804..d74f999e 100644
--- a/tokio/src/future/ready.rs
+++ b/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)))
 }
diff --git a/tokio/src/io/async_buf_read.rs b/tokio/src/io/async_buf_read.rs
index 18127351..1ab73cd9 100644
--- a/tokio/src/io/async_buf_read.rs
+++ b/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))`.
diff --git a/tokio/src/io/async_read.rs b/tokio/src/io/async_read.rs
index 24c1b4ef..de08d658 100644
--- a/tokio/src/io/async_read.rs
+++ b/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
diff --git a/tokio/src/io/async_seek.rs b/tokio/src/io/async_seek.rs
index f3e6fcdc..0be9c90d 100644
--- a/tokio/src/io/async_seek.rs
+++ b/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.
diff --git a/tokio/src/io/async_write.rs b/tokio/src/io/async_write.rs
index 8ae7cf84..0bfed056 100644
--- a/tokio/src/io/async_write.rs
+++ b/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.
diff --git a/tokio/src/io/blocking.rs b/tokio/src/io/blocking.rs
index 87b251b7..2491039a 100644
--- a/tokio/src/io/blocking.rs
+++ b/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,
 }
 
diff --git a/tokio/src/io/driver/mod.rs b/tokio/src/io/driver/mod.rs
index a36a40fa..fb3104f1 100644
--- a/tokio/src/io/driver/mod.rs
+++ b/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> {
diff --git a/tokio/src/io/poll_evented.rs b/tokio/src/io/poll_evented.rs
index 6c795b8b..c651b77e 100644
--- a/tokio/src/io/poll_evented.rs
+++ b/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
diff --git a/tokio/src/io/registration.rs b/tokio/src/io/registration.rs
index 16e8fe4d..e9497a7e 100644
--- a/tokio/src/io/registration.rs
+++ b/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.
diff --git a/tokio/src/io/split.rs b/tokio/src/io/split.rs
index 2572a786..134b937a 100644
--- a/tokio/src/io/split.rs
+++ b/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 {
diff --git a/tokio/src/io/util/async_buf_read_ext.rs b/tokio/src/io/util/async_buf_read_ext.rs
index 90789744..1bfab902 100644
--- a/tokio/src/io/util/async_buf_read_ext.rs
+++ b/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 unti