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

12 files changed, 52 insertions, 52 deletions

diff --git a/tokio/src/sync/barrier.rs b/tokio/src/sync/barrier.rs
index 911e78fe..62863349 100644
--- a/tokio/src/sync/barrier.rs
+++ b/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.
diff --git a/tokio/src/sync/broadcast.rs b/tokio/src/sync/broadcast.rs
index 35854811..515e4e4d 100644
--- a/tokio/src/sync/broadcast.rs
+++ b/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 {
diff --git a/tokio/src/sync/mpsc/block.rs b/tokio/src/sync/mpsc/block.rs
index f03648ba..4af990bf 100644
--- a/tokio/src/sync/mpsc/block.rs
+++ b/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.
diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs
index da3bd638..b95611d8 100644
--- a/tokio/src/sync/mpsc/bounded.rs
+++ b/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
diff --git a/tokio/src/sync/mpsc/chan.rs b/tokio/src/sync/mpsc/chan.rs
index 847a0b70..2fc915d0 100644
--- a/tokio/src/sync/mpsc/chan.rs
+++ b/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| {
diff --git a/tokio/src/sync/mpsc/list.rs b/tokio/src/sync/mpsc/list.rs
index dc956403..53f82a25 100644
--- a/tokio/src/sync/mpsc/list.rs
+++ b/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 {
diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs
index d1222f28..b6b621d2 100644
--- a/tokio/src/sync/mpsc/unbounded.rs
+++ b/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.
diff --git a/tokio/src/sync/mutex.rs b/tokio/src/sync/mutex.rs
index 48451357..c625ce27 100644
--- a/tokio/src/sync/mutex.rs
+++ b/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) {
diff --git a/tokio/src/sync/oneshot.rs b/tokio/src/sync/oneshot.rs
index 5bbea381..aadb4996 100644
--- a/tokio/src/sync/oneshot.rs
+++ b/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())
     }
diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs
index 13d5cfb2..7721e01f 100644
--- a/tokio/src/sync/semaphore.rs
+++ b/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) {
diff --git a/tokio/src/sync/semaphore_ll.rs b/tokio/src/sync/semaphore_ll.rs
index 6550f13d..69fd4a6a 100644
--- a/tokio/src/sync/semaphore_ll.rs
+++ b/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)
diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs
index ebcad45c..3e945563 100644
--- a/tokio/src/sync/watch.rs
+++ b/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();