From f9ddb93604a830d106475bd4c4cae436fafcc0da Mon Sep 17 00:00:00 2001 From: Oleg Nosov Date: Fri, 24 Jan 2020 20:31:13 +0300 Subject: docs: use third form in API docs (#2027) --- tokio-test/src/macros.rs | 10 ++++---- tokio-test/src/task.rs | 13 +++++----- tokio/src/fs/create_dir_all.rs | 2 +- tokio/src/fs/file.rs | 4 +-- tokio/src/fs/metadata.rs | 2 +- tokio/src/fs/read.rs | 2 +- tokio/src/fs/read_dir.rs | 4 +-- tokio/src/fs/rename.rs | 2 +- tokio/src/future/maybe_done.rs | 2 +- tokio/src/future/ready.rs | 2 +- tokio/src/io/async_buf_read.rs | 4 +-- tokio/src/io/async_read.rs | 6 ++--- tokio/src/io/async_seek.rs | 4 +-- tokio/src/io/async_write.rs | 4 +-- tokio/src/io/blocking.rs | 2 +- tokio/src/io/driver/mod.rs | 2 +- tokio/src/io/poll_evented.rs | 6 ++--- tokio/src/io/registration.rs | 12 ++++----- tokio/src/io/split.rs | 8 +++--- tokio/src/io/util/async_buf_read_ext.rs | 4 +-- tokio/src/io/util/async_read_ext.rs | 20 +++++++-------- tokio/src/io/util/async_write_ext.rs | 10 ++++---- tokio/src/io/util/buf_stream.rs | 2 +- tokio/src/loom/std/atomic_u32.rs | 2 +- tokio/src/loom/std/atomic_usize.rs | 2 +- tokio/src/macros/assert.rs | 4 +-- tokio/src/macros/cfg.rs | 6 ++--- tokio/src/net/addr.rs | 2 +- tokio/src/net/tcp/incoming.rs | 6 ++++- tokio/src/net/tcp/listener.rs | 11 +++++--- tokio/src/net/tcp/stream.rs | 12 ++++----- tokio/src/net/udp/socket.rs | 6 ++--- tokio/src/net/unix/datagram.rs | 2 +- tokio/src/net/unix/incoming.rs | 7 +++++- tokio/src/park/mod.rs | 8 +++--- tokio/src/process/kill.rs | 2 +- tokio/src/process/mod.rs | 10 ++++---- tokio/src/process/unix/orphan.rs | 4 +-- tokio/src/runtime/basic_scheduler.rs | 4 +-- tokio/src/runtime/blocking/shutdown.rs | 2 +- tokio/src/runtime/blocking/task.rs | 2 +- tokio/src/runtime/builder.rs | 24 +++++++++--------- tokio/src/runtime/handle.rs | 2 +- tokio/src/runtime/park.rs | 2 +- tokio/src/runtime/thread_pool/mod.rs | 4 +-- tokio/src/runtime/thread_pool/queue/global.rs | 2 +- tokio/src/runtime/thread_pool/queue/inject.rs | 8 +++--- tokio/src/runtime/thread_pool/queue/local.rs | 8 +++--- tokio/src/runtime/thread_pool/queue/worker.rs | 8 +++--- tokio/src/runtime/thread_pool/shutdown.rs | 2 +- tokio/src/runtime/thread_pool/slice.rs | 6 ++--- tokio/src/runtime/thread_pool/spawner.rs | 2 +- tokio/src/runtime/thread_pool/worker.rs | 10 ++++---- tokio/src/signal/registry.rs | 20 +++++++-------- tokio/src/signal/unix.rs | 8 +++--- tokio/src/signal/windows.rs | 4 +-- tokio/src/sync/barrier.rs | 2 +- tokio/src/sync/broadcast.rs | 10 ++++---- tokio/src/sync/mpsc/block.rs | 14 +++++------ tokio/src/sync/mpsc/bounded.rs | 6 ++--- tokio/src/sync/mpsc/chan.rs | 2 +- tokio/src/sync/mpsc/list.rs | 8 +++--- tokio/src/sync/mpsc/unbounded.rs | 4 +-- tokio/src/sync/mutex.rs | 2 +- tokio/src/sync/oneshot.rs | 6 ++--- tokio/src/sync/semaphore.rs | 8 +++--- tokio/src/sync/semaphore_ll.rs | 36 +++++++++++++-------------- tokio/src/sync/watch.rs | 6 ++--- tokio/src/task/blocking.rs | 4 +-- tokio/src/task/core.rs | 2 +- tokio/src/task/harness.rs | 6 ++--- tokio/src/task/local.rs | 4 +-- tokio/src/task/queue.rs | 26 +++++++++---------- tokio/src/task/state.rs | 22 ++++++++-------- tokio/src/task/yield_now.rs | 13 +++++----- tokio/src/time/delay.rs | 8 +++--- tokio/src/time/delay_queue.rs | 16 ++++++------ tokio/src/time/driver/atomic_stack.rs | 6 ++--- tokio/src/time/driver/handle.rs | 6 ++--- tokio/src/time/driver/mod.rs | 12 ++++----- tokio/src/time/driver/stack.rs | 2 +- tokio/src/time/error.rs | 4 +-- tokio/src/time/throttle.rs | 2 +- 83 files changed, 288 insertions(+), 278 deletions(-) diff --git a/tokio-test/src/macros.rs b/tokio-test/src/macros.rs index dbe2280f..299bd775 100644 --- a/tokio-test/src/macros.rs +++ b/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>` is ready and `Ok`, returning the value. +/// Asserts a `Poll>` 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>` is ready and `Err`, returning the error. +/// Asserts a `Poll>` 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. diff --git a/tokio-test/src/task.rs b/tokio-test/src/task.rs index 71ebe7b4..04328e3d 100644 --- a/tokio-test/src/task.rs +++ b/tokio-test/src/task.rs @@ -45,7 +45,7 @@ const WAKE: usize = 1; const SLEEP: usize = 2; impl Spawn { - /// 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 ops::DerefMut for Spawn { } impl Spawn { - /// Poll a future + /// Polls a future pub fn poll(&mut self) -> Poll { let fut = self.future.as_mut(); self.task.enter(|cx| fut.poll(cx)) @@ -109,7 +109,7 @@ impl Spawn { } impl Spawn { - /// Poll a stream + /// Polls a stream pub fn poll_next(&mut self) -> Poll> { let stream = self.future.as_mut(); self.task.enter(|cx| stream.poll_next(cx)) @@ -117,14 +117,14 @@ impl Spawn { } 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; 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 MaybeDone { } } - /// 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 { 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 Future for Ready { } } -/// 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: T) -> Ready> { 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>; - /// 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>; - /// 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>; - /// 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>; - /// 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 { inner: Option, state: State, - /// 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
{ 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>, } - /// 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 ReadHalf { - /// 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) -> bool { other.is_pair_of(&self) } - /// Reunite with a previously split `WriteHalf`. + /// Reunites with a previously split `WriteHalf`. /// /// # Panics /// @@ -81,7 +81,7 @@ impl ReadHalf { 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 until a newline (the 0xA byte) is reached, and append /// them to the provided buffer. /// /// Equivalent to: diff --git a/tokio/src/io/util/async_read_ext.rs b/tokio/src/io/util/async_read_ext.rs index 4ffb769c..d4402db6 100644 --- a/tokio/src/io/util/async_read_ext.rs +++ b/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: /// diff --git a/tokio/src/io/util/async_write_ext.rs b/tokio/src/io/util/async_write_ext.rs index e54501d9..377f4eca 100644 --- a/tokio/src/io/util/async_write_ext.rs +++ b/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: diff --git a/tokio/src/io/util/buf_stream.rs b/tokio/src/io/util/buf_stream.rs index 12b213d0..a56a4517 100644 --- a/tokio/src/io/util/buf_stream.rs +++ b/tokio/src/io/util/buf_stream.rs @@ -24,7 +24,7 @@ pin_project! { } impl BufStream { - /// 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 { diff --git a/tokio/src/loom/std/atomic_u32.rs b/tokio/src/loom/std/atomic_u32.rs index 0128ab2b..c83cfa2b 100644 --- a/tokio/src/loom/std/atomic_u32.rs +++ b/tokio/src/loom/std/atomic_u32.rs @@ -16,7 +16,7 @@ impl AtomicU32 { AtomicU32 { inner } } - /// Perform an unsynchronized load. + /// Performs an unsynchronized load. /// /// # Safety /// diff --git a/tokio/src/loom/std/atomic_usize.rs b/tokio/src/loom/std/atomic_usize.rs index d255d087..78644b05 100644 --- a/tokio/src/loom/std/atomic_usize.rs +++ b/tokio/src/loom/std/atomic_usize.rs @@ -16,7 +16,7 @@ impl AtomicUsize { AtomicUsize { inner } } - /// Perform an unsynchronized load. + /// Performs an unsynchronized load. /// /// # Safety /// diff --git a/tokio/src/macros/assert.rs b/tokio/src/macros/assert.rs index 4f576092..4b1cf272 100644 --- a/tokio/src/macros/assert.rs +++ b/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 { diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs index 1f168255..18beb1bd 100644 --- a/tokio/src/macros/cfg.rs +++ b/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)*) => { $( diff --git a/tokio/src/net/addr.rs b/tokio/src/net/addr.rs index d8d89c40..343d4e21 100644 --- a/tokio/src/net/addr.rs +++ b/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 /// diff --git a/tokio/src/net/tcp/incoming.rs b/tokio/src/net/tcp/incoming.rs index 0abe047d..062be1e9 100644 --- a/tokio/src/net/tcp/incoming.rs +++ b/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<'_>, diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs index 4a029b57..b1a81758 100644 --- a/tokio/src/net/tcp/listener.rs +++ b/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 diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index f3fb880b..081f6ea7 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/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 { 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 diff --git a/tokio/src/net/udp/socket.rs b/tokio/src/net/udp/socket.rs index 909ef760..604da98b 100644 --- a/tokio/src/net/udp/socket.rs +++ b/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", ) })) } diff --git a/tokio/src/net/unix/datagram.rs b/tokio/src/net/unix/datagram.rs index b41ec87c..ff0f4241 100644 --- a/tokio/src/net/unix/datagram.rs +++ b/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 diff --git a/tokio/src/net/unix/incoming.rs b/tokio/src/net/unix/incoming.rs index bede96dd..af493604 100644 --- a/tokio/src/net/unix/incoming.rs +++ b/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<'_>, diff --git a/tokio/src/park/mod.rs b/tokio/src/park/mod.rs index 13dfee2c..a3e49bbe 100644 --- a/tokio/src/park/mod.rs +++ b/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. diff --git a/tokio/src/process/kill.rs b/tokio/src/process/kill.rs index 0f7bdcbb..a1f16522 100644 --- a/tokio/src/process/kill.rs +++ b/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<()>; } diff --git a/tokio/src/process/mod.rs b/tokio/src/process/mod.rs index 6562d928..d704347c 100644 --- a/tokio/src/process/mod.rs +++ b/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. diff --git a/tokio/src/process/unix/orphan.rs b/tokio/src/process/unix/orphan.rs index 5cfdd1f6..6c449a90 100644 --- a/tokio/src/process/unix/orphan.rs +++ b/tokio/src/process/unix/orphan.rs @@ -22,9 +22,9 @@ impl Wait for &mut T { /// An interface for queueing up an orphaned process so that it can be reaped. pub(crate) trait OrphanQueue { - /// 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); } diff --git a/tokio/src/runtime/basic_scheduler.rs b/tokio/src/runtime/basic_scheduler.rs index f809db41..f625920d 100644 --- a/tokio/src/runtime/basic_scheduler.rs +++ b/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(&self, future: F) -> JoinHandle 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(&self, future: F) -> JoinHandle where F: Future + Send + 'static, diff --git a/tokio/src/runtime/blocking/shutdown.rs b/tokio/src/runtime/blocking/shutdown.rs index 8b34dbec..a7b4fc5e 100644 --- a/tokio/src/runtime/blocking/shutdown.rs +++ b/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}; diff --git a/tokio/src/runtime/blocking/task.rs b/tokio/src/runtime/blocking/task.rs index 8ea3bace..0553c9bd 100644 --- a/tokio/src/runtime/blocking/task.rs +++ b/tokio/src/runtime/blocking/task.rs @@ -8,7 +8,7 @@ pub(super) struct BlockingTask { } impl BlockingTask { - /// 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 { BlockingTask { func: Some(func) } } diff --git a/tokio/src/runtime/builder.rs b/tokio/src/runtime/builder.rs index a5d80f51..744865d6 100644 --- a/tokio/src/runtime/builder.rs +++ b/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 diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs index 3f253455..c2217413 100644 --- a/tokio/src/runtime/handle.rs +++ b/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 diff --git a/tokio/src/runtime/park.rs b/tokio/src/runtime/park.rs index c3bbe9c0..ee437d1d 100644 --- a/tokio/src/runtime/park.rs +++ b/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 diff --git a/tokio/src/runtime/thread_pool/mod.rs b/tokio/src/runtime/thread_pool/mod.rs index fd38c013..a5260356 100644 --- a/tokio/src/runtime/thread_pool/mod.rs +++ b/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(&self, future: F) -> JoinHandle 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. diff --git a/tokio/src/runtime/thread_pool/queue/global.rs b/tokio/src/runtime/thread_pool/queue/global.rs index 36dcc729..7e16280a 100644 --- a/tokio/src/runtime/thread_pool/queue/global.rs +++ b/tokio/src/runtime/thread_pool/queue/global.rs @@ -79,7 +79,7 @@ impl Queue { 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(&self, task: Task, f: F) where diff --git a/tokio/src/runtime/thread_pool/queue/inject.rs b/tokio/src/runtime/thread_pool/queue/inject.rs index 1a2d047c..d8308464 100644 --- a/tokio/src/runtime/thread_pool/queue/inject.rs +++ b/tokio/src/runtime/thread_pool/queue/inject.rs @@ -11,7 +11,7 @@ impl Inject { Inject { cluster } } - /// Push a value onto the queue + /// Pushes a value onto the queue pub(crate) fn push(&self, task: Task, f: F) where F: FnOnce(Result<(), Task>), @@ -19,12 +19,12 @@ impl Inject { 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 Inject { 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) { diff --git a/tokio/src/runtime/thread_pool/queue/local.rs b/tokio/src/runtime/thread_pool/queue/local.rs index 78b26dac..e913c4b0 100644 --- a/tokio/src/runtime/thread_pool/queue/local.rs +++ b/tokio/src/runtime/thread_pool/queue/local.rs @@ -41,7 +41,7 @@ impl Queue { } impl Queue { - /// 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, global: &global::Queue) { @@ -78,7 +78,7 @@ impl Queue { } } - /// 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 Queue { 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> { @@ -193,7 +193,7 @@ impl Queue { 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) -> Option> { let dst_tail = dst.tail.unsync_load(); diff --git a/tokio/src/runtime/thread_pool/queue/worker.rs b/tokio/src/runtime/thread_pool/queue/worker.rs index f9415669..6d364896 100644 --- a/tokio/src/runtime/thread_pool/queue/worker.rs +++ b/tokio/src/runtime/thread_pool/queue/worker.rs @@ -30,7 +30,7 @@ impl Worker { 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 Worker { 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> { 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> { 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> { diff --git a/tokio/src/runtime/thread_pool/shutdown.rs b/tokio/src/runtime/thread_pool/shutdown.rs index d9f5eb0f..414c1c84 100644 --- a/tokio/src/runtime/thread_pool/shutdown.rs +++ b/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}; diff --git a/tokio/src/runtime/thread_pool/slice.rs b/tokio/src/runtime/thread_pool/slice.rs index 05380329..9a5fd334 100644 --- a/tokio/src/runtime/thread_pool/slice.rs +++ b/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) { diff --git a/tokio/src/runtime/thread_pool/spawner.rs b/tokio/src/runtime/thread_pool/spawner.rs index 976fd32d..56931c9b 100644 --- a/tokio/src/runtime/thread_pool/spawner.rs +++ b/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(&self, future: F) -> JoinHandle where F: Future + Send + 'static, diff --git a/tokio/src/runtime/thread_pool/worker.rs b/tokio/src/runtime/thread_pool/worker.rs index e8fb74d4..5e96a442 100644 --- a/tokio/src/runtime/thread_pool/worker.rs +++ b/tokio/src/runtime/thread_pool/worker.rs @@ -182,7 +182,7 @@ impl Worker { } } - /// Acquire the lock + /// Acquires the lock fn acquire_lock(&self) -> Option> { // 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> { 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)); diff --git a/tokio/src/signal/registry.rs b/tokio/src/signal/registry.rs index d5b44cce..50edd2b6 100644 --- a/tokio/src/signal/registry.rs +++ b/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 Registry { } impl Registry { - /// 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 Registry { .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 Registry { } } - /// 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() } diff --git a/tokio/src/signal/unix.rs b/tokio/src/signal/unix.rs index 0500fa19..06f5cf4e 100644 --- a/tokio/src/signal/unix.rs +++ b/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 { } 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. diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index def1a1d7..f55e504b 100644 --- a/tokio/src/signal/windows.rs +++ b/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. 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