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

7 files changed, 38 insertions, 39 deletions

diff --git a/tokio/src/task/blocking.rs b/tokio/src/task/blocking.rs
index 69f4cf0a..0069b10a 100644
--- a/tokio/src/task/blocking.rs
+++ b/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.
diff --git a/tokio/src/task/core.rs b/tokio/src/task/core.rs
index 67b9bed6..b7c15a98 100644
--- a/tokio/src/task/core.rs
+++ b/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
diff --git a/tokio/src/task/harness.rs b/tokio/src/task/harness.rs
index 6e455507..8edcb26d 100644
--- a/tokio/src/task/harness.rs
+++ b/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);
diff --git a/tokio/src/task/local.rs b/tokio/src/task/local.rs
index ef49eebc..ed122f03 100644
--- a/tokio/src/task/local.rs
+++ b/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();
             }
diff --git a/tokio/src/task/queue.rs b/tokio/src/task/queue.rs
index 048960a4..5a2f5473 100644
--- a/tokio/src/task/queue.rs
+++ b/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
     ///
diff --git a/tokio/src/task/state.rs b/tokio/src/task/state.rs
index b764167e..e053b09e 100644
--- a/tokio/src/task/state.rs
+++ b/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;
 
diff --git a/tokio/src/task/yield_now.rs b/tokio/src/task/yield_now.rs
index e837947f..e0e20841 100644
--- a/tokio/src/task/yield_now.rs
+++ b/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"]