doc: conversion of doc comments to indicative mood (tokio-rs#4174)

Co-authored-by: Antonello Palazzi <antonello.palazzi@gmail.com>

tokio/src/coop.rs

@@ -69,14 +69,14 @@ cfg_rt_multi_thread! {
     }
 }
 
-/// Run the given closure with a cooperative task budget. When the function
+/// Runs the given closure with a cooperative task budget. When the function
 /// returns, the budget is reset to the value prior to calling the function.
 #[inline(always)]
 pub(crate) fn budget<R>(f: impl FnOnce() -> R) -> R {
     with_budget(Budget::initial(), f)
 }
 
-/// Run the given closure with an unconstrained task budget. When the function returns, the budget
+/// Runs the given closure with an unconstrained task budget. When the function returns, the budget
 /// is reset to the value prior to calling the function.
 #[inline(always)]
 pub(crate) fn with_unconstrained<R>(f: impl FnOnce() -> R) -> R {
@@ -108,7 +108,7 @@ fn with_budget<R>(budget: Budget, f: impl FnOnce() -> R) -> R {
 }
 
 cfg_rt_multi_thread! {
-    /// Set the current task's budget
+    /// Sets the current task's budget.
     pub(crate) fn set(budget: Budget) {
         CURRENT.with(|cell| cell.set(budget))
     }
@@ -120,7 +120,7 @@ cfg_rt_multi_thread! {
 }
 
 cfg_rt! {
-    /// Forcibly remove the budgeting constraints early.
+    /// Forcibly removes the budgeting constraints early.
     ///
     /// Returns the remaining budget
     pub(crate) fn stop() -> Budget {
@@ -186,7 +186,7 @@ cfg_coop! {
     }
 
     impl Budget {
-        /// Decrement the budget. Returns `true` if successful. Decrementing fails
+        /// Decrements the budget. Returns `true` if successful. Decrementing fails
         /// when there is not enough remaining budget.
         fn decrement(&mut self) -> bool {
             if let Some(num) = &mut self.0 {

tokio/src/fs/create_dir.rs

@@ -3,7 +3,7 @@ use crate::fs::asyncify;
 use std::io;
 use std::path::Path;
 
-/// Creates a new, empty directory at the provided path
+/// Creates a new, empty directory at the provided path.
 ///
 /// This is an async version of [`std::fs::create_dir`][std]
 ///

tokio/src/fs/dir_builder.rs

@@ -14,7 +14,7 @@ pub struct DirBuilder {
     /// Indicates whether to create parent directories if they are missing.
     recursive: bool,
 
-    /// Set the Unix mode for newly created directories.
+    /// Sets the Unix mode for newly created directories.
     #[cfg(unix)]
     pub(super) mode: Option<u32>,
 }

tokio/src/fs/file.rs

@@ -74,7 +74,7 @@ use std::fs::File as StdFile;
 /// # }
 /// ```
 ///
-/// Read the contents of a file into a buffer
+/// Read the contents of a file into a buffer:
 ///
 /// ```no_run
 /// use tokio::fs::File;
@@ -383,7 +383,7 @@ impl File {
         asyncify(move || std.metadata()).await
     }
 
-    /// Create a new `File` instance that shares the same underlying file handle
+    /// Creates a new `File` instance that shares the same underlying file handle
     /// as the existing `File` instance. Reads, writes, and seeks will affect both
     /// File instances simultaneously.
     ///

tokio/src/fs/open_options.rs

@@ -430,7 +430,7 @@ feature! {
             self
         }
 
-        /// Pass custom flags to the `flags` argument of `open`.
+        /// Passes custom flags to the `flags` argument of `open`.
         ///
         /// The bits that define the access mode are masked out with `O_ACCMODE`, to
         /// ensure they do not interfere with the access mode set by Rusts options.

tokio/src/fs/read_dir.rs

@@ -34,7 +34,7 @@ pub async fn read_dir(path: impl AsRef<Path>) -> io::Result<ReadDir> {
     Ok(ReadDir(State::Idle(Some(std))))
 }
 
-/// Read the the entries in a directory.
+/// Reads the the entries in a directory.
 ///
 /// This struct is returned from the [`read_dir`] function of this module and
 /// will yield instances of [`DirEntry`]. Through a [`DirEntry`] information
@@ -287,7 +287,7 @@ impl DirEntry {
         asyncify(move || std.file_type()).await
     }
 
-    /// Returns a reference to the underlying `std::fs::DirEntry`
+    /// Returns a reference to the underlying `std::fs::DirEntry`.
     #[cfg(unix)]
     pub(super) fn as_inner(&self) -> &std::fs::DirEntry {
         &self.0

tokio/src/future/maybe_done.rs

@@ -1,4 +1,4 @@
-//! Definition of the MaybeDone combinator
+//! Definition of the MaybeDone combinator.
 
 use std::future::Future;
 use std::mem;
@@ -8,9 +8,9 @@ use std::task::{Context, Poll};
 /// A future that may have completed.
 #[derive(Debug)]
 pub enum MaybeDone<Fut: Future> {
-    /// A not-yet-completed future
+    /// A not-yet-completed future.
     Future(Fut),
-    /// The output of the completed future
+    /// The output of the completed future.
     Done(Fut::Output),
     /// The empty variant after the result of a [`MaybeDone`] has been
     /// taken using the [`take_output`](MaybeDone::take_output) method.
@@ -20,7 +20,7 @@ pub enum MaybeDone<Fut: Future> {
 // Safe because we never generate `Pin<&mut Fut::Output>`
 impl<Fut: Future + Unpin> Unpin for MaybeDone<Fut> {}
 
-/// Wraps a future into a `MaybeDone`
+/// Wraps a future into a `MaybeDone`.
 pub fn maybe_done<Fut: Future>(future: Fut) -> MaybeDone<Fut> {
     MaybeDone::Future(future)
 }

tokio/src/future/poll_fn.rs

@@ -1,6 +1,6 @@
 #![allow(dead_code)]
 
-//! Definition of the `PollFn` adapter combinator
+//! Definition of the `PollFn` adapter combinator.
 
 use std::fmt;
 use std::future::Future;

tokio/src/io/async_fd.rs

@@ -205,13 +205,13 @@ impl<T: AsRawFd> AsyncFd<T> {
         })
     }
 
-    /// Returns a shared reference to the backing object of this [`AsyncFd`]
+    /// Returns a shared reference to the backing object of this [`AsyncFd`].
     #[inline]
     pub fn get_ref(&self) -> &T {
         self.inner.as_ref().unwrap()
     }
 
-    /// Returns a mutable reference to the backing object of this [`AsyncFd`]
+    /// Returns a mutable reference to the backing object of this [`AsyncFd`].
     #[inline]
     pub fn get_mut(&mut self) -> &mut T {
         self.inner.as_mut().unwrap()

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,
 }
 
@@ -175,7 +175,7 @@ where
     }
 }
 
-/// Repeats operations that are interrupted
+/// Repeats operations that are interrupted.
 macro_rules! uninterruptibly {
     ($e:expr) => {{
         loop {

tokio/src/io/bsd/poll_aio.rs

@@ -1,4 +1,4 @@
-//! Use POSIX AIO futures with Tokio
+//! Use POSIX AIO futures with Tokio.
 
 use crate::io::driver::{Handle, Interest, ReadyEvent, Registration};
 use mio::event::Source;
@@ -16,14 +16,14 @@ use std::task::{Context, Poll};
 /// Tokio's consumer must pass an implementor of this trait to create a
 /// [`Aio`] object.
 pub trait AioSource {
-    /// Register this AIO event source with Tokio's reactor
+    /// Registers this AIO event source with Tokio's reactor.
     fn register(&mut self, kq: RawFd, token: usize);
 
-    /// Deregister this AIO event source with Tokio's reactor
+    /// Deregisters this AIO event source with Tokio's reactor.
     fn deregister(&mut self);
 }
 
-/// Wrap the user's AioSource in order to implement mio::event::Source, which
+/// Wraps the user's AioSource in order to implement mio::event::Source, which
 /// is what the rest of the crate wants.
 struct MioSource<T>(T);
 

tokio/src/io/driver/interest.rs

@@ -5,7 +5,7 @@ use crate::io::driver::Ready;
 use std::fmt;
 use std::ops;
 
-/// Readiness event interest
+/// Readiness event interest.
 ///
 /// Specifies the readiness events the caller is interested in when awaiting on
 /// I/O resource readiness states.
@@ -17,19 +17,19 @@ impl Interest {
     // The non-FreeBSD definitions in this block are active only when
     // building documentation.
     cfg_aio! {
-        /// Interest for POSIX AIO
+        /// Interest for POSIX AIO.
         #[cfg(target_os = "freebsd")]
         pub const AIO: Interest = Interest(mio::Interest::AIO);
 
-        /// Interest for POSIX AIO
+        /// Interest for POSIX AIO.
         #[cfg(not(target_os = "freebsd"))]
         pub const AIO: Interest = Interest(mio::Interest::READABLE);
 
-        /// Interest for POSIX AIO lio_listio events
+        /// Interest for POSIX AIO lio_listio events.
         #[cfg(target_os = "freebsd")]
         pub const LIO: Interest = Interest(mio::Interest::LIO);
 
-        /// Interest for POSIX AIO lio_listio events
+        /// Interest for POSIX AIO lio_listio events.
         #[cfg(not(target_os = "freebsd"))]
         pub const LIO: Interest = Interest(mio::Interest::READABLE);
     }
@@ -39,7 +39,7 @@ impl Interest {
     /// Readable interest includes read-closed events.
     pub const READABLE: Interest = Interest(mio::Interest::READABLE);
 
-    /// Interest in all writable events
+    /// Interest in all writable events.
     ///
     /// Writable interest includes write-closed events.
     pub const WRITABLE: Interest = Interest(mio::Interest::WRITABLE);

tokio/src/io/driver/mod.rs

@@ -23,10 +23,10 @@ use std::io;
 use std::sync::{Arc, Weak};
 use std::time::Duration;
 
-/// I/O driver, backed by Mio
+/// I/O driver, backed by Mio.
 pub(crate) struct Driver {
     /// Tracks the number of times `turn` is called. It is safe for this to wrap
-    /// as it is mostly used to determine when to call `compact()`
+    /// as it is mostly used to determine when to call `compact()`.
     tick: u8,
 
     /// Reuse the `mio::Events` value across calls to poll.
@@ -35,17 +35,17 @@ pub(crate) struct Driver {
     /// Primary slab handle containing the state for each resource registered
     /// with this driver. During Drop this is moved into the Inner structure, so
     /// this is an Option to allow it to be vacated (until Drop this is always
-    /// Some)
+    /// Some).
     resources: Option<Slab<ScheduledIo>>,
 
-    /// The system event queue
+    /// The system event queue.
     poll: mio::Poll,
 
     /// State shared between the reactor and the handles.
     inner: Arc<Inner>,
 }
 
-/// A reference to an I/O driver
+/// A reference to an I/O driver.
 #[derive(Clone)]
 pub(crate) struct Handle {
     inner: Weak<Inner>,
@@ -66,13 +66,13 @@ pub(super) struct Inner {
     /// without risking new ones being registered in the meantime.
     resources: Mutex<Option<Slab<ScheduledIo>>>,
 
-    /// Registers I/O resources
+    /// Registers I/O resources.
     registry: mio::Registry,
 
     /// Allocates `ScheduledIo` handles when creating new resources.
     pub(super) io_dispatch: slab::Allocator<ScheduledIo>,
 
-    /// Used to wake up the reactor from a call to `turn`
+    /// Used to wake up the reactor from a call to `turn`.
     waker: mio::Waker,
 }
 
@@ -253,7 +253,7 @@ impl fmt::Debug for Driver {
 
 cfg_rt! {
     impl Handle {
-        /// Returns a handle to the current reactor
+        /// Returns a handle to the current reactor.
         ///
         /// # Panics
         ///
@@ -267,7 +267,7 @@ cfg_rt! {
 
 cfg_not_rt! {
     impl Handle {
-        /// Returns a handle to the current reactor
+        /// Returns a handle to the current reactor.
         ///
         /// # Panics
         ///

tokio/src/io/driver/ready.rs

@@ -68,7 +68,7 @@ impl Ready {
         ready
     }
 
-    /// Returns true if `Ready` is the empty set
+    /// Returns true if `Ready` is the empty set.
     ///
     /// # Examples
     ///
@@ -82,7 +82,7 @@ impl Ready {
         self == Ready::EMPTY
     }
 
-    /// Returns `true` if the value includes `readable`
+    /// Returns `true` if the value includes `readable`.
     ///
     /// # Examples
     ///
@@ -98,7 +98,7 @@ impl Ready {
         self.contains(Ready::READABLE) || self.is_read_closed()
     }
 
-    /// Returns `true` if the value includes writable `readiness`
+    /// Returns `true` if the value includes writable `readiness`.
     ///
     /// # Examples
     ///
@@ -114,7 +114,7 @@ impl Ready {
         self.contains(Ready::WRITABLE) || self.is_write_closed()
     }
 
-    /// Returns `true` if the value includes read-closed `readiness`
+    /// Returns `true` if the value includes read-closed `readiness`.
     ///
     /// # Examples
     ///
@@ -129,7 +129,7 @@ impl Ready {
         self.contains(Ready::READ_CLOSED)
     }
 
-    /// Returns `true` if the value includes write-closed `readiness`
+    /// Returns `true` if the value includes write-closed `readiness`.
     ///
     /// # Examples
     ///
@@ -154,7 +154,7 @@ impl Ready {
         (self & other) == other
     }
 
-    /// Create a `Ready` instance using the given `usize` representation.
+    /// Creates a `Ready` instance using the given `usize` representation.
     ///
     /// The `usize` representation must have been obtained from a call to
     /// `Readiness::as_usize`.