ci: add spellchecking (#6297)

.github/workflows/ci.yml

@@ -71,6 +71,7 @@ jobs:
       - check-external-types
       - check-fuzzing
       - check-unstable-mt-counters
+      - check-spelling
     steps:
       - run: exit 0
 
@@ -994,3 +995,22 @@ jobs:
       - name: Check /tokio-stream/
         run: cargo fuzz check --all-features
         working-directory: tokio-stream
+
+  check-spelling:
+    name: check-spelling
+    needs: basics
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust ${{ env.rust_stable }}
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.rust_stable }}
+      - name: Install cargo-spellcheck
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-spellcheck
+      - uses: actions/checkout@v4
+      - name: Run cargo-spellcheck
+        run: cargo spellcheck --code 1
+

CONTRIBUTING.md

@@ -194,6 +194,24 @@ MIRIFLAGS="-Zmiri-disable-isolation -Zmiri-tag-raw-pointers" \
     cargo +nightly miri test --features full --lib
 ```
 
+### Performing spellcheck on tokio codebase
+
+You can perform spell-check on tokio codebase. For details of how to use the spellcheck tool, feel free to visit
+https://github.com/drahnr/cargo-spellcheck
+```
+# First install the spell-check plugin
+cargo install --locked cargo-spellcheck
+
+# Then run the cargo spell check command
+cargo spellcheck check
+```
+
+if the command rejects a word, you should backtick the rejected word if it's code related. If not, the 
+rejected word should be put into `spellcheck.dic` file. 
+
+Note that when you add a word into the file, you should also update the first line which tells the spellcheck tool
+the total number of words included in the file
+
 ### Tests
 
 If the change being proposed alters code (as opposed to only documentation for

Cargo.toml

@@ -14,3 +14,7 @@ members = [
   "tests-build",
   "tests-integration",
 ]
+
+[workspace.metadata.spellcheck]
+config = "spellcheck.toml"
+

spellcheck.dic

@@ -0,0 +1,279 @@
+279
+\
+~
+~4
+~12
+±1m
+±1ms
+—
+&
++
+0o777
+0s
+0xA
+0xD
+100ms
+10ms
+1ms
+1s
+250ms
+2x
+443
+450ms
+50ms
+8MB
+<
+=
+>
+adaptor
+adaptors
+Adaptors
+AIO
+ambiant
+amongst
+api
+APIs
+async
+awaitable
+backend
+backpressure
+backtrace
+backtraces
+backtracing
+binded
+bitfield
+bitfields
+Blockingly
+boolean
+broadcasted
+cancelled
+cancelling
+Cancelling
+CLI
+cloneable
+codebase
+codec
+codecs
+combinator
+combinators
+Config
+config
+connectionless
+cpu
+cpus
+Customizable
+Datagram
+datagram
+datagrams
+deallocate
+deallocated
+Deallocates
+decrementing
+dequeued
+deregister
+deregistered
+deregistering
+Deregisters
+deregisters
+deregistration
+descriptor's
+destructor
+destructors
+destructure
+Destructures
+Dev
+dns
+DNS
+DoS
+dwOpenMode
+endian
+enqueue
+enqueued
+EntryInner
+enum
+eof
+errored
+EWMA
+expirations
+fcntl
+fd's
+FIFOs
+filename
+filesystem
+filesystems
+fn
+fns
+FreeBSD
+frontend
+fs
+functionalities
+getters
+GID
+Growable
+gzip
+hashmaps
+HashMaps
+hashsets
+ie
+Illumos
+impl
+implementers
+implementor
+implementors
+incrementing
+interoperate
+Invariants
+invariants
+io
+IOCP
+iOS
+IOs
+IP
+IPv4
+IPv6
+iteratively
+latencies
+Lauck
+libc
+lifecycle
+lifo
+lookups
+macOS
+MacOS
+Marsaglia's
+metadata
+mio
+Mio
+mio's
+misconfigured
+mock's
+mpmc
+mpsc
+Multi
+multi
+multicast
+Multithreaded
+mut
+mutex
+Mutex
+Nagle
+nonblocking
+nondecreasing
+noop
+ntasks
+ok
+oneshot
+ORed
+os
+overweighing
+parker
+parsers
+peekable
+PGID
+PID
+plaintext
+poller
+POSIX
+proxied
+qos
+RAII
+reallocations
+recv's
+refactors
+refcount
+refcounting
+repo
+repr
+representable
+reqwest
+reregistering
+resize
+resized
+RMW
+runtime
+runtimes
+runtime's
+rwlock
+rx
+scalability
+scheduler's
+semver
+setpgid
+sharded
+signalled
+signalling
+SmallCrush
+Solaris
+spawner
+Splitter
+spmc
+spsc
+src
+stabilised
+startup
+stateful
+stderr
+stdin
+stdout
+stealable
+stealer
+stealers
+struct
+structs
+subfield
+suboptimal
+subprocess
+superset
+symlink
+symlinks
+sys
+syscall
+syscalls
+TCP
+tcp
+TestU01
+threadpool
+timestamp
+timestamps
+TLS
+TOCTOU
+TODO
+Tokio
+tokio
+tokio's
+Tokio's
+Tuple
+tuple
+tx
+UDP
+udp
+UID
+unhandled
+unix
+unlink
+unpark
+Unpark
+unparked
+unparking
+Unparks
+unparks
+unreceived
+unsafety
+Unsets
+unsynchronized
+untrusted
+usecases
+Valgrind
+Varghese
+vec
+versa
+versioned
+versioning
+vtable
+waker
+wakers
+Wakers
+wakeup
+wakeups
+workstealing
+

spellcheck.toml

@@ -0,0 +1,13 @@
+dev_comments = false
+skip_readme = false
+
+[Hunspell]
+lang = "en_US"
+search_dirs = ["."]
+extra_dictionaries = ["spellcheck.dic"]
+skip_os_lookups = true
+use_builtin = true
+
+[Hunspell.quirks]
+allow_concatenation = true
+

tokio-stream/src/lib.rs

@@ -54,7 +54,7 @@
 //!
 //! [async-stream]: https://docs.rs/async-stream
 //!
-//! # Conversion to and from AsyncRead/AsyncWrite
+//! # Conversion to and from `AsyncRead`/`AsyncWrite`
 //!
 //! It is often desirable to convert a `Stream` into an [`AsyncRead`],
 //! especially when dealing with plaintext formats streamed over the network.

tokio-stream/src/stream_map.rs

@@ -658,9 +658,9 @@ mod rand {
 
     /// Fast random number generate
     ///
-    /// Implement xorshift64+: 2 32-bit xorshift sequences added together.
+    /// Implement `xorshift64+`: 2 32-bit `xorshift` sequences added together.
     /// Shift triplet `[17,7,16]` was calculated as indicated in Marsaglia's
-    /// Xorshift paper: <https://www.jstatsoft.org/article/view/v008i14/xorshift.pdf>
+    /// `Xorshift` paper: <https://www.jstatsoft.org/article/view/v008i14/xorshift.pdf>
     /// This generator passes the SmallCrush suite, part of TestU01 framework:
     /// <http://simul.iro.umontreal.ca/testu01/tu01.html>
     #[derive(Debug)]

tokio-stream/src/wrappers/watch.rs

@@ -10,7 +10,7 @@ use tokio::sync::watch::error::RecvError;
 
 /// A wrapper around [`tokio::sync::watch::Receiver`] that implements [`Stream`].
 ///
-/// This stream will start by yielding the current value when the WatchStream is polled,
+/// This stream will start by yielding the current value when the `WatchStream` is polled,
 /// regardless of whether it was the initial value or sent afterwards,
 /// unless you use [`WatchStream<T>::from_changes`].
 ///

tokio-util/src/codec/framed.rs

@@ -130,7 +130,7 @@ impl<T, U> Framed<T, U> {
     /// things like gzip or TLS, which require both read and write access to the
     /// underlying object.
     ///
-    /// This objects takes a stream and a readbuffer and a writebuffer. These field
+    /// This objects takes a stream and a `readbuffer` and a `writebuffer`. These field
     /// can be obtained from an existing `Framed` with the [`into_parts`] method.
     ///
     /// If you want to work more directly with the streams and sink, consider

tokio-util/src/codec/mod.rs

@@ -1,4 +1,4 @@
-//! Adaptors from AsyncRead/AsyncWrite to Stream/Sink
+//! Adaptors from `AsyncRead`/`AsyncWrite` to Stream/Sink
 //!
 //! Raw I/O objects work with byte sequences, but higher-level code usually
 //! wants to batch these into meaningful chunks, called "frames".

tokio-util/src/io/inspect.rs

@@ -18,7 +18,7 @@ pin_project! {
 }
 
 impl<R, F> InspectReader<R, F> {
-    /// Create a new InspectReader, wrapping `reader` and calling `f` for the
+    /// Create a new `InspectReader`, wrapping `reader` and calling `f` for the
     /// new data supplied by each read call.
     ///
     /// The closure will only be called with an empty slice if the inner reader
@@ -100,7 +100,7 @@ pin_project! {
 }
 
 impl<W, F> InspectWriter<W, F> {
-    /// Create a new InspectWriter, wrapping `write` and calling `f` for the
+    /// Create a new `InspectWriter`, wrapping `write` and calling `f` for the
     /// data successfully written by each write call.
     ///
     /// The closure `f` will never be called with an empty slice. A vectored

tokio-util/src/sync/cancellation_token/tree_node.rs

@@ -1,16 +1,16 @@
-//! This mod provides the logic for the inner tree structure of the CancellationToken.
+//! This mod provides the logic for the inner tree structure of the `CancellationToken`.
 //!
-//! CancellationTokens are only light handles with references to [`TreeNode`].
+//! `CancellationTokens` are only light handles with references to [`TreeNode`].
 //! All the logic is actually implemented in the [`TreeNode`].
 //!
 //! A [`TreeNode`] is part of the cancellation tree and may have one parent and an arbitrary number of
 //! children.
 //!
-//! A [`TreeNode`] can receive the request to perform a cancellation through a CancellationToken.
+//! A [`TreeNode`] can receive the request to perform a cancellation through a `CancellationToken`.
 //! This cancellation request will cancel the node and all of its descendants.
 //!
 //! As soon as a node cannot get cancelled any more (because it was already cancelled or it has no
-//! more CancellationTokens pointing to it any more), it gets removed from the tree, to keep the
+//! more `CancellationTokens` pointing to it any more), it gets removed from the tree, to keep the
 //! tree as small as possible.
 //!
 //! # Invariants
@@ -66,7 +66,7 @@ impl TreeNode {
     }
 }
 
-/// The data contained inside a TreeNode.
+/// The data contained inside a `TreeNode`.
 ///
 /// This struct exists so that the data of the node can be wrapped
 /// in a Mutex.
@@ -198,7 +198,7 @@ where
 /// `parent` MUST have been a parent of the node when they both got locked,
 /// otherwise there is a potential for a deadlock as invariant #2 would be violated.
 ///
-/// To acquire the locks for node and parent, use [with_locked_node_and_parent].
+/// To acquire the locks for node and parent, use [`with_locked_node_and_parent`].
 fn move_children_to_parent(node: &mut Inner, parent: &mut Inner) {
     // Pre-allocate in the parent, for performance
     parent.children.reserve(node.children.len());
@@ -216,7 +216,7 @@ fn move_children_to_parent(node: &mut Inner, parent: &mut Inner) {
 /// Removes a child from the parent.
 ///
 /// `parent` MUST be the parent of `node`.
-/// To acquire the locks for node and parent, use [with_locked_node_and_parent].
+/// To acquire the locks for node and parent, use [`with_locked_node_and_parent`].
 fn remove_child(parent: &mut Inner, mut node: MutexGuard<'_, Inner>) {
     // Query the position from where to remove a node
     let pos = node.parent_idx;

tokio-util/src/task/join_map.rs

@@ -878,7 +878,7 @@ impl<K: Eq> Eq for Key<K> {}
 #[derive(Debug, Clone)]
 pub struct JoinMapKeys<'a, K, V> {
     iter: hashbrown::hash_map::Keys<'a, Key<K>, AbortHandle>,
-    /// To make it easier to change JoinMap in the future, keep V as a generic
+    /// To make it easier to change `JoinMap` in the future, keep V as a generic
     /// parameter.
     _value: PhantomData<&'a V>,
 }

tokio/src/doc/os.rs

@@ -1,67 +1,67 @@
-//! See [std::os](https://doc.rust-lang.org/std/os/index.html).
+//! See [`std::os`](https://doc.rust-lang.org/std/os/index.html).
 
 /// Platform-specific extensions to `std` for Windows.
 ///
-/// See [std::os::windows](https://doc.rust-lang.org/std/os/windows/index.html).
+/// See [`std::os::windows`](https://doc.rust-lang.org/std/os/windows/index.html).
 pub mod windows {
     /// Windows-specific extensions to general I/O primitives.
     ///
-    /// See [std::os::windows::io](https://doc.rust-lang.org/std/os/windows/io/index.html).
+    /// See [`std::os::windows::io`](https://doc.rust-lang.org/std/os/windows/io/index.html).
     pub mod io {
-        /// See [std::os::windows::io::RawHandle](https://doc.rust-lang.org/std/os/windows/io/type.RawHandle.html)
+        /// See [`std::os::windows::io::RawHandle`](https://doc.rust-lang.org/std/os/windows/io/type.RawHandle.html)
         pub type RawHandle = crate::doc::NotDefinedHere;
 
-        /// See [std::os::windows::io::OwnedHandle](https://doc.rust-lang.org/std/os/windows/io/struct.OwnedHandle.html)
+        /// See [`std::os::windows::io::OwnedHandle`](https://doc.rust-lang.org/std/os/windows/io/struct.OwnedHandle.html)
         pub type OwnedHandle = crate::doc::NotDefinedHere;
 
-        /// See [std::os::windows::io::AsRawHandle](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html)
+        /// See [`std::os::windows::io::AsRawHandle`](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html)
         pub trait AsRawHandle {
-            /// See [std::os::windows::io::AsRawHandle::as_raw_handle](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html#tymethod.as_raw_handle)
+            /// See [`std::os::windows::io::AsRawHandle::as_raw_handle`](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawHandle.html#tymethod.as_raw_handle)
             fn as_raw_handle(&self) -> RawHandle;
         }
 
-        /// See [std::os::windows::io::FromRawHandle](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html)
+        /// See [`std::os::windows::io::FromRawHandle`](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html)
         pub trait FromRawHandle {
-            /// See [std::os::windows::io::FromRawHandle::from_raw_handle](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html#tymethod.from_raw_handle)
+            /// See [`std::os::windows::io::FromRawHandle::from_raw_handle`](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawHandle.html#tymethod.from_raw_handle)
             unsafe fn from_raw_handle(handle: RawHandle) -> Self;
         }
 
-        /// See [std::os::windows::io::RawSocket](https://doc.rust-lang.org/std/os/windows/io/type.RawSocket.html)
+        /// See [`std::os::windows::io::RawSocket`](https://doc.rust-lang.org/std/os/windows/io/type.RawSocket.html)
         pub type RawSocket = crate::doc::NotDefinedHere;
 
-        /// See [std::os::windows::io::AsRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html)
+        /// See [`std::os::windows::io::AsRawSocket`](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html)
         pub trait AsRawSocket {
-            /// See [std::os::windows::io::AsRawSocket::as_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html#tymethod.as_raw_socket)
+            /// See [`std::os::windows::io::AsRawSocket::as_raw_socket`](https://doc.rust-lang.org/std/os/windows/io/trait.AsRawSocket.html#tymethod.as_raw_socket)
             fn as_raw_socket(&self) -> RawSocket;
         }
 
-        /// See [std::os::windows::io::FromRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html)
+        /// See [`std::os::windows::io::FromRawSocket`](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html)
         pub trait FromRawSocket {
-            /// See [std::os::windows::io::FromRawSocket::from_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html#tymethod.from_raw_socket)
+            /// See [`std::os::windows::io::FromRawSocket::from_raw_socket`](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html#tymethod.from_raw_socket)
             unsafe fn from_raw_socket(sock: RawSocket) -> Self;
         }
 
-        /// See [std::os::windows::io::IntoRawSocket](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html)
+        /// See [`std::os::windows::io::IntoRawSocket`](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html)
         pub trait IntoRawSocket {
-            /// See [std::os::windows::io::IntoRawSocket::into_raw_socket](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html#tymethod.into_raw_socket)
+            /// See [`std::os::windows::io::IntoRawSocket::into_raw_socket`](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html#tymethod.into_raw_socket)
             fn into_raw_socket(self) -> RawSocket;
         }
 
-        /// See [std::os::windows::io::BorrowedHandle](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedHandle.html)
+        /// See [`std::os::windows::io::BorrowedHandle`](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedHandle.html)
         pub type BorrowedHandle<'handle> = crate::doc::NotDefinedHere;
 
-        /// See [std::os::windows::io::AsHandle](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html)
+        /// See [`std::os::windows::io::AsHandle`](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html)
         pub trait AsHandle {
-            /// See [std::os::windows::io::AsHandle::as_handle](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html#tymethod.as_handle)
+            /// See [`std::os::windows::io::AsHandle::as_handle`](https://doc.rust-lang.org/std/os/windows/io/trait.AsHandle.html#tymethod.as_handle)
             fn as_handle(&self) -> BorrowedHandle<'_>;
         }
 
-        /// See [std::os::windows::io::BorrowedSocket](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedSocket.html)
+        /// See [`std::os::windows::io::BorrowedSocket`](https://doc.rust-lang.org/std/os/windows/io/struct.BorrowedSocket.html)
         pub type BorrowedSocket<'socket> = crate::doc::NotDefinedHere;
 
-        /// See [std::os::windows::io::AsSocket](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html)
+        /// See [`std::os::windows::io::AsSocket`](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html)
         pub trait AsSocket {
-            /// See [std::os::windows::io::AsSocket::as_socket](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html#tymethod.as_socket)
+            /// See [`std::os::windows::io::AsSocket::as_socket`](https://doc.rust-lang.org/std/os/windows/io/trait.AsSocket.html#tymethod.as_socket)
             fn as_socket(&self) -> BorrowedSocket<'_>;
         }
     }

tokio/src/fs/open_options/mock_open_options.rs

@@ -1,5 +1,5 @@
 #![allow(unreachable_pub)]
-//! Mock version of std::fs::OpenOptions;
+//! Mock version of `std::fs::OpenOptions`;
 use mockall::mock;
 
 use crate::fs::mocks::MockFile;

tokio/src/io/interest.rs

@@ -40,11 +40,11 @@ impl Interest {
         #[cfg(not(target_os = "freebsd"))]
         pub const AIO: Interest = 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(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(READABLE);
     }

tokio/src/io/mod.rs

@@ -4,7 +4,7 @@
 //! defines two traits, [`AsyncRead`] and [`AsyncWrite`], which are asynchronous
 //! versions of the [`Read`] and [`Write`] traits in the standard library.
 //!
-//! # AsyncRead and AsyncWrite
+//! # `AsyncRead` and `AsyncWrite`
 //!
 //! Like the standard library's [`Read`] and [`Write`] traits, [`AsyncRead`] and
 //! [`AsyncWrite`] provide the most general interface for reading and writing
@@ -122,7 +122,7 @@
 //! [`BufReader`]: crate::io::BufReader
 //! [`BufWriter`]: crate::io::BufWriter
 //!
-//! ## Implementing AsyncRead and AsyncWrite
+//! ## Implementing `AsyncRead` and `AsyncWrite`
 //!
 //! Because they are traits, we can implement [`AsyncRead`] and [`AsyncWrite`] for
 //! our own types, as well. Note that these traits must only be implemented for

tokio/src/io/poll_evented.rs

@@ -47,7 +47,7 @@ cfg_io_driver! {
     /// This clears the readiness state until a new readiness event is received.
     ///
     /// This allows the caller to implement additional functions. For example,
-    /// [`TcpListener`] implements poll_accept by using [`poll_read_ready`] and
+    /// [`TcpListener`] implements `poll_accept` by using [`poll_read_ready`] and
     /// [`clear_readiness`].
     ///
     /// ## Platform-specific events

tokio/src/io/stdio_common.rs

@@ -4,7 +4,7 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 /// # Windows
 /// [`AsyncWrite`] adapter that finds last char boundary in given buffer and does not write the rest,
-/// if buffer contents seems to be utf8. Otherwise it only trims buffer down to `MAX_BUF`.
+/// if buffer contents seems to be `utf8`. Otherwise it only trims buffer down to `MAX_BUF`.
 /// That's why, wrapped writer will always receive well-formed utf-8 bytes.
 /// # Other platforms
 /// Passes data to `inner` as is.

tokio/src/io/util/async_buf_read_ext.rs

@@ -302,7 +302,7 @@ cfg_io_util! {
         ///
         /// The stream returned from this function will yield instances of
         /// [`io::Result`]`<`[`Option`]`<`[`String`]`>>`. Each string returned will *not* have a newline
-        /// byte (the 0xA byte) or CRLF (0xD, 0xA bytes) at the end.
+        /// byte (the 0xA byte) or `CRLF` (0xD, 0xA bytes) at the end.
         ///
         /// [`io::Result`]: std::io::Result
         /// [`Option`]: core::option::Option

tokio/src/io/util/buf_reader.rs

@@ -145,13 +145,13 @@ impl<R: AsyncRead> AsyncBufRead for BufReader<R> {
 
 #[derive(Debug, Clone, Copy)]
 pub(super) enum SeekState {
-    /// start_seek has not been called.
+    /// `start_seek` has not been called.
     Init,
-    /// start_seek has been called, but poll_complete has not yet been called.
+    /// `start_seek` has been called, but `poll_complete` has not yet been called.
     Start(SeekFrom),
-    /// Waiting for completion of the first poll_complete in the `n.checked_sub(remainder).is_none()` branch.
+    /// Waiting for completion of the first `poll_complete` in the `n.checked_sub(remainder).is_none()` branch.
     PendingOverflowed(i64),
-    /// Waiting for completion of poll_complete.
+    /// Waiting for completion of `poll_complete`.
     Pending,
 }
 

tokio/src/io/util/buf_writer.rs

@@ -212,11 +212,11 @@ impl<W: AsyncWrite> AsyncWrite for BufWriter<W> {
 
 #[derive(Debug, Clone, Copy)]
 pub(super) enum SeekState {
-    /// start_seek has not been called.
+    /// `start_seek` has not been called.
     Init,
-    /// start_seek has been called, but poll_complete has not yet been called.
+    /// `start_seek` has been called, but `poll_complete` has not yet been called.
     Start(SeekFrom),
-    /// Waiting for completion of poll_complete.
+    /// Waiting for completion of `poll_complete`.
     Pending,
 }
 

tokio/src/io/util/read_exact.rs

@@ -12,7 +12,7 @@ use std::task::{Context, Poll};
 /// a buffer.
 ///
 /// Created by the [`AsyncReadExt::read_exact`][read_exact].
-/// [read_exact]: [crate::io::AsyncReadExt::read_exact]
+/// [`read_exact`]: [`crate::io::AsyncReadExt::read_exact`]
 pub(crate) fn read_exact<'a, A>(reader: &'a mut A, buf: &'a mut [u8]) -> ReadExact<'a, A>
 where
     A: AsyncRead + Unpin + ?Sized,

tokio/src/io/util/read_line.rs

@@ -51,7 +51,7 @@ fn put_back_original_data(output: &mut String, mut vector: Vec<u8>, num_bytes_re
 
 /// This handles the various failure cases and puts the string back into `output`.
 ///
-/// The `truncate_on_io_error` bool is necessary because `read_to_string` and `read_line`
+/// The `truncate_on_io_error` `bool` is necessary because `read_to_string` and `read_line`
 /// disagree on what should happen when an IO error occurs.
 pub(super) fn finish_string_read(
     io_res: io::Result<usize>,

tokio/src/io/util/shutdown.rs

@@ -11,7 +11,7 @@ pin_project! {
     /// A future used to shutdown an I/O object.
     ///
     /// Created by the [`AsyncWriteExt::shutdown`][shutdown] function.
-    /// [shutdown]: crate::io::AsyncWriteExt::shutdown
+    /// [shutdown]: [`crate::io::AsyncWriteExt::shutdown`]
     #[must_use = "futures do nothing unless you `.await` or poll them"]
     #[derive(Debug)]
     pub struct Shutdown<'a, A: ?Sized> {

tokio/src/lib.rs

@@ -31,8 +31,8 @@
 //! * APIs for [performing asynchronous I/O][io], including [TCP and UDP][net] sockets,
 //!   [filesystem][fs] operations, and [process] and [signal] management.
 //! * A [runtime] for executing asynchronous code, including a task scheduler,
-//!   an I/O driver backed by the operating system's event queue (epoll, kqueue,
-//!   IOCP, etc...), and a high performance timer.
+//!   an I/O driver backed by the operating system's event queue (`epoll`, `kqueue`,
+//!   `IOCP`, etc...), and a high performance timer.
 //!
 //! Guide level documentation is found on the [website].
 //!
@@ -330,11 +330,11 @@
 //! - `signal`: Enables all `tokio::signal` types.
 //! - `fs`: Enables `tokio::fs` types.
 //! - `test-util`: Enables testing based infrastructure for the Tokio runtime.
-//! - `parking_lot`: As a potential optimization, use the _parking_lot_ crate's
+//! - `parking_lot`: As a potential optimization, use the `_parking_lot_` crate's
 //!                  synchronization primitives internally. Also, this
 //!                  dependency is necessary to construct some of our primitives
-//!                  in a const context. MSRV may increase according to the
-//!                  _parking_lot_ release in use.
+//!                  in a `const` context. `MSRV` may increase according to the
+//!                  `_parking_lot_` release in use.
 //!
 //! _Note: `AsyncRead` and `AsyncWrite` traits do not require any features and are
 //! always available._
@@ -409,9 +409,9 @@
 //!
 //! [mio-supported]: https://crates.io/crates/mio#platforms
 //!
-//! ### WASM support
+//! ### `WASM` support
 //!
-//! Tokio has some limited support for the WASM platform. Without the
+//! Tokio has some limited support for the `WASM` platform. Without the
 //! `tokio_unstable` flag, the following features are supported:
 //!
 //!  * `sync`
@@ -423,22 +423,22 @@
 //! Enabling any other feature (including `full`) will cause a compilation
 //! failure.
 //!
-//! The `time` module will only work on WASM platforms that have support for
-//! timers (e.g. wasm32-wasi). The timing functions will panic if used on a WASM
+//! The `time` module will only work on `WASM` platforms that have support for
+//! timers (e.g. wasm32-wasi). The timing functions will panic if used on a `WASM`
 //! platform that does not support timers.
 //!
 //! Note also that if the runtime becomes indefinitely idle, it will panic
 //! immediately instead of blocking forever. On platforms that don't support
 //! time, this means that the runtime can never be idle in any way.
 //!
-//! ### Unstable WASM support
+//! ### Unstable `WASM` support
 //!
-//! Tokio also has unstable support for some additional WASM features. This
+//! Tokio also has unstable support for some additional `WASM` features. This
 //! requires the use of the `tokio_unstable` flag.
 //!
 //! Using this flag enables the use of `tokio::net` on the wasm32-wasi target.
-//! However, not all methods are available on the networking types as WASI
-//! currently does not support the creation of new sockets from within WASM.
+//! However, not all methods are available on the networking types as `WASI`
+//! currently does not support the creation of new sockets from within `WASM`.
 //! Because of this, sockets must currently be created via the `FromRawFd`
 //! trait.
 
@@ -596,7 +596,7 @@ mod util;
 /// reach `std` on a stable compiler in time for the 1.0 release of Tokio. For
 /// this reason, the team has decided to move all `Stream` based utilities to
 /// the [`tokio-stream`] crate. While this is not ideal, once `Stream` has made
-/// it into the standard library and the MSRV period has passed, we will implement
+/// it into the standard library and the `MSRV` period has passed, we will implement
 /// stream for our different types.
 ///
 /// While this may seem unfortunate, not all is lost as you can get much of the
@@ -689,6 +689,6 @@ cfg_macros! {
 #[cfg(test)]
 fn is_unpin<T: Unpin>() {}
 
-/// fuzz test (fuzz_linked_list)
+/// fuzz test (`fuzz_linked_list`)
 #[cfg(fuzzing)]
 pub mod fuzz;

tokio/src/loom/std/atomic_u64.rs

@@ -1,4 +1,4 @@
-//! Implementation of an atomic u64 cell. On 64 bit platforms, this is a
+//! Implementation of an atomic `u64` cell. On 64 bit platforms, this is a
 //! re-export of `AtomicU64`. On 32 bit platforms, this is implemented using a
 //! `Mutex`.
 

tokio/src/macros/cfg.rs

@@ -49,7 +49,7 @@ macro_rules! cfg_unstable_windows {
     }
 }
 
-/// Enables enter::block_on.
+/// Enables `enter::block_on`.
 macro_rules! cfg_block_on {
     ($($item:item)*) => {
         $(

tokio/src/macros/try_join.rs

@@ -30,7 +30,7 @@
 ///
 /// # Examples
 ///
-/// Basic try_join with two branches.
+/// Basic `try_join` with two branches.
 ///
 /// ```
 /// async fn do_stuff_async() -> Result<(), &'static str> {

tokio/src/net/tcp/listener.rs

@@ -58,7 +58,7 @@ cfg_net! {
 
 impl TcpListener {
     cfg_not_wasi! {
-        /// Creates a new TcpListener, which will be bound to the specified address.
+        /// Creates a new `TcpListener`, which will be bound to the specified address.
         ///
         /// The returned listener is ready for accepting connections.
         ///

tokio/src/net/tcp/stream.rs

@@ -1060,7 +1060,7 @@ impl TcpStream {
     /// returns the number of bytes peeked.
     ///
     /// Successive calls return the same data. This is accomplished by passing
-    /// `MSG_PEEK` as a flag to the underlying recv system call.
+    /// `MSG_PEEK` as a flag to the underlying `recv` system call.
     ///
     /// # Examples
     ///
@@ -1178,13 +1178,13 @@ impl TcpStream {
             socket2::SockRef::from(self).linger()
         }
 
-        /// Sets the linger duration of this socket by setting the SO_LINGER option.
+        /// Sets the linger duration of this socket by setting the `SO_LINGER` option.
         ///
         /// This option controls the action taken when a stream has unsent messages and the stream is
-        /// closed. If SO_LINGER is set, the system shall block the process until it can transmit the
+        /// closed. If `SO_LINGER` is set, the system shall block the process until it can transmit the
         /// data or until the time expires.
         ///
-        /// If SO_LINGER is not specified, and the stream is closed, the system handles the call in a
+        /// If `SO_LINGER` is not specified, and the stream is closed, the system handles the call in a
         /// way that allows the process to continue as quickly as possible.
         ///
         /// # Examples

tokio/src/net/udp.rs

@@ -180,7 +180,7 @@ impl UdpSocket {
     /// This function is intended to be used to wrap a UDP socket from the
     /// standard library in the Tokio equivalent.
     ///
-    /// This can be used in conjunction with socket2's `Socket` interface to
+    /// This can be used in conjunction with `socket2`'s `Socket` interface to
     /// configure a socket before it's handed off, such as setting options like
     /// `reuse_address` or binding to multiple addresses.
     ///
@@ -313,7 +313,7 @@ impl UdpSocket {
     }
 
     /// Connects the UDP socket setting the default destination for send() and
-    /// limiting packets that are read via recv from the address specified in
+    /// limiting packets that are read via `recv` from the address specified in
     /// `addr`.
     ///
     /// # Example
@@ -358,7 +358,7 @@ impl UdpSocket {
     /// Waits for any of the requested ready states.
     ///
     /// This function is usually paired with `try_recv()` or `try_send()`. It
-    /// can be used to concurrently recv / send to the same socket on a single
+    /// can be used to concurrently `recv` / `send` to the same socket on a single
     /// task without splitting the socket.
     ///
     /// The function may complete without the socket being ready. This is a
@@ -786,7 +786,7 @@ impl UdpSocket {
     /// The [`connect`] method will connect this socket to a remote address. This method
     /// resolves to an error if the socket is not connected.
     ///
-    /// Note that on multiple calls to a `poll_*` method in the recv direction, only the
+    /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the
     /// `Waker` from the `Context` passed to the most recent call will be scheduled to
     /// receive a wakeup.
     ///
@@ -825,7 +825,7 @@ impl UdpSocket {
     /// address to which it is connected. On success, returns the number of
     /// bytes read.
     ///
-    /// This method must be called with valid byte array buf of sufficient size
+    /// This method must be called with valid byte array `buf` of sufficient size
     /// to hold the message bytes. If a message is too long to fit in the
     /// supplied buffer, excess bytes may be discarded.
     ///
@@ -881,7 +881,7 @@ impl UdpSocket {
         /// Tries to receive data from the stream into the provided buffer, advancing the
         /// buffer's internal cursor, returning how many bytes were read.
         ///
-        /// This method must be called with valid byte array buf of sufficient size
+        /// This method must be called with valid byte array `buf` of sufficient size
         /// to hold the message bytes. If a message is too long to fit in the
         /// supplied buffer, excess bytes may be discarded.
         ///
@@ -949,7 +949,7 @@ impl UdpSocket {
         /// to which it is connected, advancing the buffer's internal cursor,
         /// returning how many bytes were read.
         ///
-        /// This method must be called with valid byte array buf of sufficient size
+        /// This method must be called with valid byte array `buf` of sufficient size
         /// to hold the message bytes. If a message is too long to fit in the
         /// supplied buffer, excess bytes may be discarded.
         ///
@@ -996,7 +996,7 @@ impl UdpSocket {
         /// Tries to receive a single datagram message on the socket. On success,
         /// returns the number of bytes read and the origin.
         ///
-        /// This method must be called with valid byte array buf of sufficient size
+        /// This method must be called with valid byte array `buf` of sufficient size
         /// to hold the message bytes. If a message is too long to fit in the
         /// supplied buffer, excess bytes may be discarded.
         ///
@@ -1071,7 +1071,7 @@ impl UdpSocket {
         /// Receives a single datagram message on the socket, advancing the
         /// buffer's internal cursor, returning how many bytes were read and the origin.
         ///
-        /// This method must be called with valid byte array buf of sufficient size
+        /// This method must be called with valid byte array `buf` of sufficient size
         /// to hold the message bytes. If a message is too long to fit in the
         /// supplied buffer, excess bytes may be discarded.
         ///
@@ -1311,7 +1311,7 @@ impl UdpSocket {
 
     /// Attempts to receive a single datagram on the socket.
     ///
-    /// Note that on multiple calls to a `poll_*` method in the recv direction, only the
+    /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the
     /// `Waker` from the `Context` passed to the most recent call will be scheduled to
     /// receive a wakeup.
     ///
@@ -1360,7 +1360,7 @@ impl UdpSocket {
     /// Tries to receive a single datagram message on the socket. On success,
     /// returns the number of bytes read and the origin.
     ///
-    /// This method must be called with valid byte array buf of sufficient size
+    /// This method must be called with valid byte array `buf` of sufficient size
     /// to hold the message bytes. If a message is too long to fit in the
     /// supplied buffer, excess bytes may be discarded.
     ///
@@ -1507,7 +1507,7 @@ impl UdpSocket {
     ///
     /// On Windows, if the data is larger than the buffer specified, the buffer
     /// is filled with the first part of the data, and `peek_from` returns the error
-    /// WSAEMSGSIZE(10040). The excess data is lost.
+    /// `WSAEMSGSIZE(10040)`. The excess data is lost.
     /// Make sure to always use a sufficiently large buffer to hold the
     /// maximum UDP packet size, which can be up to 65536 bytes in size.
     ///
@@ -1555,13 +1555,13 @@ impl UdpSocket {
     ///
     /// # Notes
     ///
-    /// Note that on multiple calls to a `poll_*` method in the recv direction, only the
+    /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the
     /// `Waker` from the `Context` passed to the most recent call will be scheduled to
     /// receive a wakeup
     ///
     /// On Windows, if the data is larger than the buffer specified, the buffer
     /// is filled with the first part of the data, and peek returns the error
-    /// WSAEMSGSIZE(10040). The excess data is lost.
+    /// `WSAEMSGSIZE(10040)`. The excess data is lost.
     /// Make sure to always use a sufficiently large buffer to hold the
     /// maximum UDP packet size, which can be up to 65536 bytes in size.
     ///
@@ -1623,7 +1623,7 @@ impl UdpSocket {
     ///
     /// On Windows, if the data is larger than the buffer specified, the buffer
     /// is filled with the first part of the data, and peek returns the error
-    /// WSAEMSGSIZE(10040). The excess data is lost.
+    /// `WSAEMSGSIZE(10040)`. The excess data is lost.
     /// Make sure to always use a sufficiently large buffer to hold the
     /// maximum UDP packet size, which can be up to 65536 bytes in size.
     ///
@@ -1674,7 +1674,7 @@ impl UdpSocket {
     ///
     /// # Notes
     ///
-    /// Note that on multiple calls to a `poll_*` method in the recv direction, only the
+    /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the
     /// `Waker` from the `Context` passed to the most recent call will be scheduled to
     /// receive a wakeup.
     ///

tokio/src/net/unix/datagram/socket.rs

@@ -109,7 +109,7 @@ impl UnixDatagram {
     /// Waits for any of the requested ready states.
     ///
     /// This function is usually paired with `try_recv()` or `try_send()`. It
-    /// can be used to concurrently recv / send to the same socket on a single
+    /// can be used to concurrently `recv` / `send` to the same socket on a single
     /// task without splitting the socket.
     ///
     /// The function may complete without the socket being ready. This is a
@@ -435,12 +435,12 @@ impl UnixDatagram {
 
     /// Creates new [`UnixDatagram`] from a [`std::os::unix::net::UnixDatagram`].
     ///
-    /// This function is intended to be used to wrap a UnixDatagram from the
+    /// This function is intended to be used to wrap a `UnixDatagram` from the
     /// standard library in the Tokio equivalent.
     ///
     /// # Notes
     ///
-    /// The caller is responsible for ensuring that the socker is in
+    /// The caller is responsible for ensuring that the socket is in
     /// non-blocking mode. Otherwise all I/O operations on the socket
     /// will block the thread, which will cause unexpected behavior.
     /// Non-blocking mode can be set using [`set_nonblocking`].
@@ -1141,7 +1141,7 @@ impl UnixDatagram {
 
     /// Attempts to receive a single datagram on the specified address.
     ///
-    /// Note that on multiple calls to a `poll_*` method in the recv direction, only the
+    /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the
     /// `Waker` from the `Context` passed to the most recent call will be scheduled to
     /// receive a wakeup.
     ///
@@ -1244,7 +1244,7 @@ impl UnixDatagram {
     /// The [`connect`] method will connect this socket to a remote address. This method
     /// resolves to an error if the socket is not connected.
     ///
-    /// Note that on multiple calls to a `poll_*` method in the recv direction, only the
+    /// Note that on multiple calls to a `poll_*` method in the `recv` direction, only the
     /// `Waker` from the `Context` passed to the most recent call will be scheduled to
     /// receive a wakeup.
     ///

tokio/src/net/unix/listener.rs

@@ -77,7 +77,7 @@ impl UnixListener {
 
     /// Creates new [`UnixListener`] from a [`std::os::unix::net::UnixListener`].
     ///
-    /// This function is intended to be used to wrap a UnixListener from the
+    /// This function is intended to be used to wrap a `UnixListener` from the
     /// standard library in the Tokio equivalent.
     ///
     /// # Notes

tokio/src/net/unix/stream.rs

@@ -762,7 +762,7 @@ impl UnixStream {
 
     /// Creates new [`UnixStream`] from a [`std::os::unix::net::UnixStream`].
     ///
-    /// This function is intended to be used to wrap a UnixStream from the
+    /// This function is intended to be used to wrap a `UnixStream` from the
     /// standard library in the Tokio equivalent.
     ///
     /// # Notes

tokio/src/net/windows/named_pipe.rs

@@ -2059,7 +2059,7 @@ impl ServerOptions {
     ///
     /// ```
     /// use std::{io, os::windows::prelude::AsRawHandle, ptr};
-    //
+    ///
     /// use tokio::net::windows::named_pipe::ServerOptions;
     /// use windows_sys::{
     ///     Win32::Foundation::ERROR_SUCCESS,
@@ -2094,7 +2094,7 @@ impl ServerOptions {
     ///
     /// ```
     /// use std::{io, os::windows::prelude::AsRawHandle, ptr};
-    //
+    ///
     /// use tokio::net::windows::named_pipe::ServerOptions;
     /// use windows_sys::{
     ///     Win32::Foundation::ERROR_ACCESS_DENIED,

tokio/src/process/mod.rs

@@ -739,12 +739,12 @@ impl Command {
     }
 
     /// Sets the process group ID (PGID) of the child process. Equivalent to a
-    /// setpgid call in the child process, but may be more efficient.
+    /// `setpgid` call in the child process, but may be more efficient.
     ///
     /// Process groups determine which processes receive signals.
     ///
     /// **Note**: This is an [unstable API][unstable] but will be stabilised once
-    /// tokio's MSRV is sufficiently new. See [the documentation on
+    /// tokio's `MSRV` is sufficiently new. See [the documentation on
     /// unstable features][unstable] for details about using unstable features.
     ///
     /// If you want similar behavior without using this unstable feature you can
@@ -1109,7 +1109,7 @@ impl Child {
     /// Attempts to force the child to exit, but does not wait for the request
     /// to take effect.
     ///
-    /// On Unix platforms, this is the equivalent to sending a SIGKILL. Note
+    /// On Unix platforms, this is the equivalent to sending a `SIGKILL`. Note
     /// that on Unix platforms it is possible for a zombie process to remain
     /// after a kill is sent; to avoid this, the caller should ensure that either
     /// `child.wait().await` or `child.try_wait()` is invoked successfully.
@@ -1125,12 +1125,12 @@ impl Child {
 
     /// Forces the child to exit.
     ///
-    /// This is equivalent to sending a SIGKILL on unix platforms.
+    /// This is equivalent to sending a `SIGKILL` on unix platforms.
     ///
     /// If the child has to be killed remotely, it is possible to do it using
-    /// a combination of the select! macro and a oneshot channel. In the following
+    /// a combination of the select! macro and a `oneshot` channel. In the following
     /// example, the child will run until completion unless a message is sent on
-    /// the oneshot channel. If that happens, the child is killed immediately
+    /// the `oneshot` channel. If that happens, the child is killed immediately
     /// using the `.kill()` method.
     ///
     /// ```no_run

tokio/src/runtime/blocking/pool.rs

@@ -105,16 +105,16 @@ struct Shared {
     num_notify: u32,
     shutdown: bool,
     shutdown_tx: Option<shutdown::Sender>,
-    /// Prior to shutdown, we clean up JoinHandles by having each timed-out
+    /// Prior to shutdown, we clean up `JoinHandles` by having each timed-out
     /// thread join on the previous timed-out thread. This is not strictly
     /// necessary but helps avoid Valgrind false positives, see
     /// <https://github.com/tokio-rs/tokio/commit/646fbae76535e397ef79dbcaacb945d4c829f666>
     /// for more information.
     last_exiting_thread: Option<thread::JoinHandle<()>>,
-    /// This holds the JoinHandles for all running threads; on shutdown, the thread
+    /// This holds the `JoinHandles` for all running threads; on shutdown, the thread
     /// calling shutdown handles joining on these.
     worker_threads: HashMap<usize, thread::JoinHandle<()>>,
-    /// This is a counter used to iterate worker_threads in a consistent order (for loom's
+    /// This is a counter used to iterate `worker_threads` in a consistent order (for loom's
     /// benefit).
     worker_thread_index: usize,
 }

tokio/src/runtime/builder.rs

@@ -78,7 +78,7 @@ pub struct Builder {
     /// To run after each thread is unparked.
     pub(super) after_unpark: Option<Callback>,
 
-    /// Customizable keep alive timeout for BlockingPool
+    /// Customizable keep alive timeout for `BlockingPool`
     pub(super) keep_alive: Option<Duration>,
 
     /// How many ticks before pulling a task from the global/remote queue?
@@ -723,7 +723,7 @@ impl Builder {
     /// Sets a custom timeout for a thread in the blocking pool.
     ///
     /// By default, the timeout for a thread is set to 10 seconds. This can
-    /// be overridden using .thread_keep_alive().
+    /// be overridden using `.thread_keep_alive()`.
     ///
     /// # Example
     ///

tokio/src/runtime/context.rs

@@ -61,7 +61,7 @@ struct Context {
     rng: Cell<Option<FastRand>>,
 
     /// Tracks the amount of "work" a task may still do before yielding back to
-    /// the sheduler
+    /// the scheduler
     budget: Cell<coop::Budget>,
 
     #[cfg(all(

tokio/src/runtime/handle.rs

@@ -463,7 +463,7 @@ cfg_taskdump! {
         /// ## Debug Info Must Be Available
         ///
         /// To produce task traces, the application must **not** be compiled
-        /// with split debuginfo. On Linux, including debuginfo within the
+        /// with `split debuginfo`. On Linux, including `debuginfo` within the
         /// application binary is the (correct) default. You can further ensure
         /// this behavior with the following directive in your `Cargo.toml`:
         ///
@@ -475,7 +475,7 @@ cfg_taskdump! {
         /// ## Unstable Features
         ///
         /// This functionality is **unstable**, and requires both the
-        /// `tokio_unstable` and `tokio_taskdump` cfg flags to be set.
+        /// `tokio_unstable` and `tokio_taskdump` `cfg` flags to be set.
         ///
         /// You can do this by setting the `RUSTFLAGS` environment variable
         /// before invoking `cargo`; e.g.:
@@ -495,7 +495,7 @@ cfg_taskdump! {
         ///
         /// ## Platform Requirements
         ///
-        /// Task dumps are supported on Linux atop aarch64, x86 and x86_64.
+        /// Task dumps are supported on Linux atop `aarch64`, `x86` and `x86_64`.
         ///
         /// ## Current Thread Runtime Requirements
         ///

tokio/src/runtime/io/driver.rs

@@ -40,7 +40,7 @@ pub(crate) struct Handle {
     synced: Mutex<registration_set::Synced>,
 
     /// Used to wake up the reactor from a call to `turn`.
-    /// Not supported on Wasi due to lack of threading support.
+    /// Not supported on `Wasi` due to lack of threading support.
     #[cfg(not(target_os = "wasi"))]
     waker: mio::Waker,
 

tokio/src/runtime/io/scheduled_io.rs

@@ -114,10 +114,10 @@ struct Waiters {
     /// List of all current waiters.
     list: WaitList,
 
-    /// Waker used for AsyncRead.
+    /// Waker used for `AsyncRead`.
     reader: Option<Waker>,
 
-    /// Waker used for AsyncWrite.
+    /// Waker used for `AsyncWrite`.
     writer: Option<Waker>,
 }
 
@@ -191,7 +191,7 @@ impl ScheduledIo {
         mio::Token(self as *const _ as usize)
     }
 
-    /// Invoked when the IO driver is shut down; forces this ScheduledIo into a
+    /// Invoked when the IO driver is shut down; forces this `ScheduledIo` into a
     /// permanently shutdown state.
     pub(super) fn shutdown(&self) {
         let mask = SHUTDOWN.pack(1, 0);

tokio/src/runtime/scheduler/multi_thread/park.rs

@@ -22,10 +22,10 @@ struct Inner {
     /// Avoids entering the park if possible
     state: AtomicUsize,
 
-    /// Used to coordinate access to the driver / condvar
+    /// Used to coordinate access to the driver / `condvar`
     mutex: Mutex<()>,
 
-    /// Condvar to block on if the driver is unavailable.
+    /// `Condvar` to block on if the driver is unavailable.
     condvar: Condvar,
 
     /// Resource (I/O, time, ...) driver

tokio/src/runtime/scheduler/multi_thread/queue.rs

@@ -36,8 +36,8 @@ pub(crate) struct Steal<T: 'static>(Arc<Inner<T>>);
 pub(crate) struct Inner<T: 'static> {
     /// Concurrently updated by many threads.
     ///
-    /// Contains two `UnsignedShort` values. The LSB byte is the "real" head of
-    /// the queue. The `UnsignedShort` in the MSB is set by a stealer in process
+    /// Contains two `UnsignedShort` values. The `LSB` byte is the "real" head of
+    /// the queue. The `UnsignedShort` in the `MSB` is set by a stealer in process
     /// of stealing values. It represents the first value being stolen in the
     /// batch. The `UnsignedShort` indices are intentionally wider than strictly
     /// required for buffer indexing in order to provide ABA mitigation and make

tokio/src/runtime/scheduler/multi_thread/stats.rs

@@ -22,7 +22,7 @@ pub(crate) struct Stats {
     /// Exponentially-weighted moving average of time spent polling scheduled a
     /// task.
     ///
-    /// Tracked in nanoseconds, stored as a f64 since that is what we use with
+    /// Tracked in nanoseconds, stored as a `f64` since that is what we use with
     /// the EWMA calculations
     task_poll_time_ewma: f64,
 }

tokio/src/runtime/scheduler/multi_thread/worker.rs

@@ -9,19 +9,19 @@
 //! Shutting down the runtime involves the following steps:
 //!
 //!  1. The Shared::close method is called. This closes the inject queue and
-//!     OwnedTasks instance and wakes up all worker threads.
+//!     `OwnedTasks` instance and wakes up all worker threads.
 //!
 //!  2. Each worker thread observes the close signal next time it runs
 //!     Core::maintenance by checking whether the inject queue is closed.
-//!     The Core::is_shutdown flag is set to true.
+//!     The `Core::is_shutdown` flag is set to true.
 //!
 //!  3. The worker thread calls `pre_shutdown` in parallel. Here, the worker
-//!     will keep removing tasks from OwnedTasks until it is empty. No new
-//!     tasks can be pushed to the OwnedTasks during or after this step as it
+//!     will keep removing tasks from `OwnedTasks` until it is empty. No new
+//!     tasks can be pushed to the `OwnedTasks` during or after this step as it
 //!     was closed in step 1.
 //!
 //!  5. The workers call Shared::shutdown to enter the single-threaded phase of
-//!     shutdown. These calls will push their core to Shared::shutdown_cores,
+//!     shutdown. These calls will push their core to `Shared::shutdown_cores`,
 //!     and the last thread to push its core will finish the shutdown procedure.
 //!
 //!  6. The local run queue of each core is emptied, then the inject queue is
@@ -35,22 +35,22 @@
 //!
 //! When spawning tasks during shutdown, there are two cases:
 //!
-//!  * The spawner observes the OwnedTasks being open, and the inject queue is
+//!  * The spawner observes the `OwnedTasks` being open, and the inject queue is
 //!    closed.
-//!  * The spawner observes the OwnedTasks being closed and doesn't check the
+//!  * The spawner observes the `OwnedTasks` being closed and doesn't check the
 //!    inject queue.
 //!
-//! The first case can only happen if the OwnedTasks::bind call happens before
+//! The first case can only happen if the `OwnedTasks::bind` call happens before
 //! or during step 1 of shutdown. In this case, the runtime will clean up the
 //! task in step 3 of shutdown.
 //!
 //! In the latter case, the task was not spawned and the task is immediately
 //! cancelled by the spawner.
 //!
-//! The correctness of shutdown requires both the inject queue and OwnedTasks
+//! The correctness of shutdown requires both the inject queue and `OwnedTasks`
 //! collection to have a closed bit. With a close bit on only the inject queue,
 //! spawning could run in to a situation where a task is successfully bound long
-//! after the runtime has shut down. With a close bit on only the OwnedTasks,
+//! after the runtime has shut down. With a close bit on only the `OwnedTasks`,
 //! the first spawning situation could result in the notification being pushed
 //! to the inject queue after step 6 of shutdown, which would leave a task in
 //! the inject queue indefinitely. This would be a ref-count cycle and a memory
@@ -184,7 +184,7 @@ pub(crate) struct Shared {
     /// Only held to trigger some code on drop. This is used to get internal
     /// runtime metrics that can be useful when doing performance
     /// investigations. This does nothing (empty struct, no drop impl) unless
-    /// the `tokio_internal_mt_counters` cfg flag is set.
+    /// the `tokio_internal_mt_counters` `cfg` flag is set.
     _counters: Counters,
 }
 
@@ -234,7 +234,7 @@ type Task = task::Task<Arc<Handle>>;
 type Notified = task::Notified<Arc<Handle>>;
 
 /// Value picked out of thin-air. Running the LIFO slot a handful of times
-/// seemms sufficient to benefit from locality. More than 3 times probably is
+/// seems sufficient to benefit from locality. More than 3 times probably is
 /// overweighing. The value can be tuned in the future with data that shows
 /// improvements.
 const MAX_LIFO_POLLS_PER_TICK: usize = 3;
@@ -677,7 +677,7 @@ impl Context {
     /// Also important to notice that, before parking, the worker thread will try to take
     /// ownership of the Driver (IO/Time) and dispatch any events that might have fired.
     /// Whenever a worker thread executes the Driver loop, all waken tasks are scheduled
-    /// in its own local queue until the queue saturates (ntasks > LOCAL_QUEUE_CAPACITY).
+    /// in its own local queue until the queue saturates (ntasks > `LOCAL_QUEUE_CAPACITY`).
     /// When the local queue is saturated, the overflow tasks are added to the injection queue
     /// from where other workers can pick them up.
     /// Also, we rely on the workstealing algorithm to spread the tasks amongst workers

tokio/src/runtime/scheduler/multi_thread_alt/queue.rs

@@ -37,8 +37,8 @@ pub(crate) struct Steal<T: 'static>(Arc<Inner<T>>);
 pub(crate) struct Inner<T: 'static> {
     /// Concurrently updated by many threads.
     ///
-    /// Contains two `UnsignedShort` values. The LSB byte is the "real" head of
-    /// the queue. The `UnsignedShort` in the MSB is set by a stealer in process
+    /// Contains two `UnsignedShort` values. The `LSB` byte is the "real" head of
+    /// the queue. The `UnsignedShort` in the `MSB` is set by a stealer in process
     /// of stealing values. It represents the first value being stolen in the
     /// batch. The `UnsignedShort` indices are intentionally wider than strictly
     /// required for buffer indexing in order to provide ABA mitigation and make

tokio/src/runtime/scheduler/multi_thread_alt/stats.rs

@@ -13,7 +13,7 @@ pub(crate) struct Stats {
     /// Exponentially-weighted moving average of time spent polling scheduled a
     /// task.
     ///
-    /// Tracked in nanoseconds, stored as a f64 since that is what we use with
+    /// Tracked in nanoseconds, stored as a `f64` since that is what we use with
     /// the EWMA calculations
     task_poll_time_ewma: f64,
 }

tokio/src/runtime/scheduler/multi_thread_alt/worker.rs

@@ -9,19 +9,19 @@
 //! Shutting down the runtime involves the following steps:
 //!
 //!  1. The Shared::close method is called. This closes the inject queue and
-//!     OwnedTasks instance and wakes up all worker threads.
+//!     `OwnedTasks` instance and wakes up all worker threads.
 //!
 //!  2. Each worker thread observes the close signal next time it runs
 //!     Core::maintenance by checking whether the inject queue is closed.
-//!     The Core::is_shutdown flag is set to true.
+//!     The `Core::is_shutdown` flag is set to true.
 //!
 //!  3. The worker thread calls `pre_shutdown` in parallel. Here, the worker
-//!     will keep removing tasks from OwnedTasks until it is empty. No new
-//!     tasks can be pushed to the OwnedTasks during or after this step as it
+//!     will keep removing tasks from `OwnedTasks` until it is empty. No new
+//!     tasks can be pushed to the `OwnedTasks` during or after this step as it
 //!     was closed in step 1.
 //!
 //!  5. The workers call Shared::shutdown to enter the single-threaded phase of
-//!     shutdown. These calls will push their core to Shared::shutdown_cores,
+//!     shutdown. These calls will push their core to `Shared::shutdown_cores`,
 //!     and the last thread to push its core will finish the shutdown procedure.
 //!
 //!  6. The local run queue of each core is emptied, then the inject queue is
@@ -35,22 +35,22 @@
 //!
 //! When spawning tasks during shutdown, there are two cases:
 //!
-//!  * The spawner observes the OwnedTasks being open, and the inject queue is
+//!  * The spawner observes the `OwnedTasks` being open, and the inject queue is
 //!    closed.
-//!  * The spawner observes the OwnedTasks being closed and doesn't check the
+//!  * The spawner observes the `OwnedTasks` being closed and doesn't check the
 //!    inject queue.
 //!
-//! The first case can only happen if the OwnedTasks::bind call happens before
+//! The first case can only happen if the `OwnedTasks::bind` call happens before
 //! or during step 1 of shutdown. In this case, the runtime will clean up the
 //! task in step 3 of shutdown.
 //!
 //! In the latter case, the task was not spawned and the task is immediately
 //! cancelled by the spawner.
 //!
-//! The correctness of shutdown requires both the inject queue and OwnedTasks
+//! The correctness of shutdown requires both the inject queue and `OwnedTasks`
 //! collection to have a closed bit. With a close bit on only the inject queue,
 //! spawning could run in to a situation where a task is successfully bound long
-//! after the runtime has shut down. With a close bit on only the OwnedTasks,
+//! after the runtime has shut down. With a close bit on only the `OwnedTasks`,
 //! the first spawning situation could result in the notification being pushed
 //! to the inject queue after step 6 of shutdown, which would leave a task in
 //! the inject queue indefinitely. This would be a ref-count cycle and a memory
@@ -157,7 +157,7 @@ pub(crate) struct Shared {
     driver: AtomicCell<Driver>,
 
     /// Condition variables used to unblock worker threads. Each worker thread
-    /// has its own condvar it waits on.
+    /// has its own `condvar` it waits on.
     pub(super) condvars: Vec<Condvar>,
 
     /// The number of cores that have observed the trace signal.
@@ -174,7 +174,7 @@ pub(crate) struct Shared {
     /// Only held to trigger some code on drop. This is used to get internal
     /// runtime metrics that can be useful when doing performance
     /// investigations. This does nothing (empty struct, no drop impl) unless
-    /// the `tokio_internal_mt_counters` cfg flag is set.
+    /// the `tokio_internal_mt_counters` `cfg` flag is set.
     _counters: Counters,
 }
 
@@ -248,7 +248,7 @@ type Task = task::Task<Arc<Handle>>;
 type Notified = task::Notified<Arc<Handle>>;
 
 /// Value picked out of thin-air. Running the LIFO slot a handful of times
-/// seemms sufficient to benefit from locality. More than 3 times probably is
+/// seems sufficient to benefit from locality. More than 3 times probably is
 /// overweighing. The value can be tuned in the future with data that shows
 /// improvements.
 const MAX_LIFO_POLLS_PER_TICK: usize = 3;

tokio/src/runtime/task/core.rs

@@ -28,7 +28,7 @@ use std::task::{Context, Poll, Waker};
 /// be referenced by both *mut Cell and *mut Header.
 ///
 /// Any changes to the layout of this struct _must_ also be reflected in the
-/// const fns in raw.rs.
+/// `const` fns in raw.rs.
 ///
 // # This struct should be cache padded to avoid false sharing. The cache padding rules are copied
 // from crossbeam-utils/src/cache_padded.rs
@@ -132,7 +132,7 @@ pub(super) struct CoreStage<T: Future> {
 /// Holds the future or output, depending on the stage of execution.
 ///
 /// Any changes to the layout of this struct _must_ also be reflected in the
-/// const fns in raw.rs.
+/// `const` fns in raw.rs.
 #[repr(C)]
 pub(super) struct Core<T: Future, S> {
     /// Scheduler used to drive this future.

tokio/src/runtime/task/harness.rs

@@ -183,7 +183,7 @@ where
     /// If the return value is Complete, the caller is given ownership of a
     /// single ref-count, which should be passed on to `complete`.
     ///
-    /// If the return value is Dealloc, then this call consumed the last
+    /// If the return value is `Dealloc`, then this call consumed the last
     /// ref-count and the caller should call `dealloc`.
     ///
     /// Otherwise the ref-count is consumed and the caller should not access

tokio/src/runtime/task/join.rs

@@ -58,7 +58,7 @@ cfg_rt! {
     /// ```
     ///
     /// The generic parameter `T` in `JoinHandle<T>` is the return type of the spawned task.
-    /// If the return value is an i32, the join handle has type `JoinHandle<i32>`:
+    /// If the return value is an `i32`, the join handle has type `JoinHandle<i32>`:
     ///
     /// ```
     /// use tokio::task;

tokio/src/runtime/task/list.rs

@@ -84,8 +84,8 @@ impl<S: 'static> OwnedTasks<S> {
         }
     }
 
-    /// Binds the provided task to this OwnedTasks instance. This fails if the
-    /// OwnedTasks has been closed.
+    /// Binds the provided task to this `OwnedTasks` instance. This fails if the
+    /// `OwnedTasks` has been closed.
     pub(crate) fn bind<T>(
         &self,
         task: T,
@@ -125,8 +125,8 @@ impl<S: 'static> OwnedTasks<S> {
         Some(notified)
     }
 
-    /// Asserts that the given task is owned by this OwnedTasks and convert it to
-    /// a LocalNotified, giving the thread permission to poll this task.
+    /// Asserts that the given task is owned by this `OwnedTasks` and convert it to
+    /// a `LocalNotified`, giving the thread permission to poll this task.
     #[inline]
     pub(crate) fn assert_owner(&self, task: Notified<S>) -> LocalNotified<S> {
         debug_assert_eq!(task.header().get_owner_id(), Some(self.id));
@@ -284,8 +284,8 @@ impl<S: 'static> LocalOwnedTasks<S> {
             unsafe { inner.list.remove(task.header_ptr()) })
     }
 
-    /// Asserts that the given task is owned by this LocalOwnedTasks and convert
-    /// it to a LocalNotified, giving the thread permission to poll this task.
+    /// Asserts that the given task is owned by this `LocalOwnedTasks` and convert
+    /// it to a `LocalNotified`, giving the thread permission to poll this task.
     #[inline]
     pub(crate) fn assert_owner(&self, task: Notified<S>) -> LocalNotified<S> {
         assert_eq!(task.header().get_owner_id(), Some(self.id));

tokio/src/runtime/task/mod.rs

@@ -2,52 +2,52 @@
 //!
 //! The task module contains the code that manages spawned tasks and provides a
 //! safe API for the rest of the runtime to use. Each task in a runtime is
-//! stored in an OwnedTasks or LocalOwnedTasks object.
+//! stored in an `OwnedTasks` or `LocalOwnedTasks` object.
 //!
 //! # Task reference types
 //!
 //! A task is usually referenced by multiple handles, and there are several
 //! types of handles.
 //!
-//!  * OwnedTask - tasks stored in an OwnedTasks or LocalOwnedTasks are of this
+//!  * `OwnedTask` - tasks stored in an `OwnedTasks` or `LocalOwnedTasks` are of this
 //!    reference type.
 //!
-//!  * JoinHandle - each task has a JoinHandle that allows access to the output
+//!  * `JoinHandle` - each task has a `JoinHandle` that allows access to the output
 //!    of the task.
 //!
-//!  * Waker - every waker for a task has this reference type. There can be any
+//!  * `Waker` - every waker for a task has this reference type. There can be any
 //!    number of waker references.
 //!
-//!  * Notified - tracks whether the task is notified.
+//!  * `Notified` - tracks whether the task is notified.
 //!
-//!  * Unowned - this task reference type is used for tasks not stored in any
+//!  * `Unowned` - this task reference type is used for tasks not stored in any
 //!    runtime. Mainly used for blocking tasks, but also in tests.
 //!
 //! The task uses a reference count to keep track of how many active references
-//! exist. The Unowned reference type takes up two ref-counts. All other
+//! exist. The `Unowned` reference type takes up two ref-counts. All other
 //! reference types take up a single ref-count.
 //!
 //! Besides the waker type, each task has at most one of each reference type.
 //!
 //! # State
 //!
-//! The task stores its state in an atomic usize with various bitfields for the
+//! The task stores its state in an atomic `usize` with various bitfields for the
 //! necessary information. The state has the following bitfields:
 //!
-//!  * RUNNING - Tracks whether the task is currently being polled or cancelled.
+//!  * `RUNNING` - Tracks whether the task is currently being polled or cancelled.
 //!    This bit functions as a lock around the task.
 //!
-//!  * COMPLETE - Is one once the future has fully completed and has been
+//!  * `COMPLETE` - Is one once the future has fully completed and has been
 //!    dropped. Never unset once set. Never set together with RUNNING.
 //!
-//!  * NOTIFIED - Tracks whether a Notified object currently exists.
+//!  * `NOTIFIED` - Tracks whether a Notified object currently exists.
 //!
-//!  * CANCELLED - Is set to one for tasks that should be cancelled as soon as
+//!  * `CANCELLED` - Is set to one for tasks that should be cancelled as soon as
 //!    possible. May take any value for completed tasks.
 //!
-//!  * JOIN_INTEREST - Is set to one if there exists a JoinHandle.
+//!  * `JOIN_INTEREST` - Is set to one if there exists a `JoinHandle`.
 //!
-//!  * JOIN_WAKER - Acts as an access control bit for the join handle waker. The
+//!  * `JOIN_WAKER` - Acts as an access control bit for the join handle waker. The
 //!    protocol for its usage is described below.
 //!
 //! The rest of the bits are used for the ref-count.
@@ -59,7 +59,7 @@
 //!
 //!  * The state field is accessed with atomic instructions.
 //!
-//!  * The OwnedTask reference has exclusive access to the `owned` field.
+//!  * The `OwnedTask` reference has exclusive access to the `owned` field.
 //!
 //!  * The Notified reference has exclusive access to the `queue_next` field.
 //!
@@ -67,42 +67,42 @@
 //!    is otherwise immutable and anyone can access the field immutably without
 //!    synchronization.
 //!
-//!  * If COMPLETE is one, then the JoinHandle has exclusive access to the
+//!  * If COMPLETE is one, then the `JoinHandle` has exclusive access to the
 //!    stage field. If COMPLETE is zero, then the RUNNING bitfield functions as
 //!    a lock for the stage field, and it can be accessed only by the thread
 //!    that set RUNNING to one.
 //!
 //!  * The waker field may be concurrently accessed by different threads: in one
 //!    thread the runtime may complete a task and *read* the waker field to
-//!    invoke the waker, and in another thread the task's JoinHandle may be
-//!    polled, and if the task hasn't yet completed, the JoinHandle may *write*
-//!    a waker to the waker field. The JOIN_WAKER bit ensures safe access by
+//!    invoke the waker, and in another thread the task's `JoinHandle` may be
+//!    polled, and if the task hasn't yet completed, the `JoinHandle` may *write*
+//!    a waker to the waker field. The `JOIN_WAKER` bit ensures safe access by
 //!    multiple threads to the waker field using the following rules:
 //!
-//!    1. JOIN_WAKER is initialized to zero.
+//!    1. `JOIN_WAKER` is initialized to zero.
 //!
-//!    2. If JOIN_WAKER is zero, then the JoinHandle has exclusive (mutable)
+//!    2. If `JOIN_WAKER` is zero, then the `JoinHandle` has exclusive (mutable)
 //!       access to the waker field.
 //!
-//!    3. If JOIN_WAKER is one, then the JoinHandle has shared (read-only)
+//!    3. If `JOIN_WAKER` is one, then the `JoinHandle` has shared (read-only)
 //!       access to the waker field.
 //!
-//!    4. If JOIN_WAKER is one and COMPLETE is one, then the runtime has shared
+//!    4. If `JOIN_WAKER` is one and COMPLETE is one, then the runtime has shared
 //!       (read-only) access to the waker field.
 //!
-//!    5. If the JoinHandle needs to write to the waker field, then the
-//!       JoinHandle needs to (i) successfully set JOIN_WAKER to zero if it is
+//!    5. If the `JoinHandle` needs to write to the waker field, then the
+//!       `JoinHandle` needs to (i) successfully set `JOIN_WAKER` to zero if it is
 //!       not already zero to gain exclusive access to the waker field per rule
-//!       2, (ii) write a waker, and (iii) successfully set JOIN_WAKER to one.
+//!       2, (ii) write a waker, and (iii) successfully set `JOIN_WAKER` to one.
 //!
-//!    6. The JoinHandle can change JOIN_WAKER only if COMPLETE is zero (i.e.
+//!    6. The `JoinHandle` can change `JOIN_WAKER` only if COMPLETE is zero (i.e.
 //!       the task hasn't yet completed).
 //!
 //!    Rule 6 implies that the steps (i) or (iii) of rule 5 may fail due to a
 //!    race. If step (i) fails, then the attempt to write a waker is aborted. If
 //!    step (iii) fails because COMPLETE is set to one by another thread after
 //!    step (i), then the waker field is cleared. Once COMPLETE is one (i.e.
-//!    task has completed), the JoinHandle will not modify JOIN_WAKER. After the
+//!    task has completed), the `JoinHandle` will not modify `JOIN_WAKER`. After the
 //!    runtime sets COMPLETE to one, it invokes the waker if there is one.
 //!
 //! All other fields are immutable and can be accessed immutably without
@@ -119,18 +119,18 @@
 //! the RUNNING field, so exclusive access is ensured.
 //!
 //! When the task completes, exclusive access to the output is transferred to
-//! the JoinHandle. If the JoinHandle is already dropped when the transition to
+//! the `JoinHandle`. If the `JoinHandle` is already dropped when the transition to
 //! complete happens, the thread performing that transition retains exclusive
 //! access to the output and should immediately drop it.
 //!
 //! ## Non-Send futures
 //!
-//! If a future is not Send, then it is bound to a LocalOwnedTasks.  The future
-//! will only ever be polled or dropped given a LocalNotified or inside a call
-//! to LocalOwnedTasks::shutdown_all. In either case, it is guaranteed that the
+//! If a future is not Send, then it is bound to a `LocalOwnedTasks`.  The future
+//! will only ever be polled or dropped given a `LocalNotified` or inside a call
+//! to `LocalOwnedTasks::shutdown_all`. In either case, it is guaranteed that the
 //! future is on the right thread.
 //!
-//! If the task is never removed from the LocalOwnedTasks, then it is leaked, so
+//! If the task is never removed from the `LocalOwnedTasks`, then it is leaked, so
 //! there is no risk that the task is dropped on some other thread when the last
 //! ref-count drops.
 //!
@@ -138,21 +138,21 @@
 //!
 //! When a task completes, the output is placed in the stage of the task. Then,
 //! a transition that sets COMPLETE to true is performed, and the value of
-//! JOIN_INTEREST when this transition happens is read.
+//! `JOIN_INTEREST` when this transition happens is read.
 //!
-//! If JOIN_INTEREST is zero when the transition to COMPLETE happens, then the
+//! If `JOIN_INTEREST` is zero when the transition to COMPLETE happens, then the
 //! output is immediately dropped.
 //!
-//! If JOIN_INTEREST is one when the transition to COMPLETE happens, then the
-//! JoinHandle is responsible for cleaning up the output. If the output is not
+//! If `JOIN_INTEREST` is one when the transition to COMPLETE happens, then the
+//! `JoinHandle` is responsible for cleaning up the output. If the output is not
 //! Send, then this happens:
 //!
 //!  1. The output is created on the thread that the future was polled on. Since
 //!     only non-Send futures can have non-Send output, the future was polled on
 //!     the thread that the future was spawned from.
 //!  2. Since `JoinHandle<Output>` is not Send if Output is not Send, the
-//!     JoinHandle is also on the thread that the future was spawned from.
-//!  3. Thus, the JoinHandle will not move the output across threads when it
+//!     `JoinHandle` is also on the thread that the future was spawned from.
+//!  3. Thus, the `JoinHandle` will not move the output across threads when it
 //!     takes or drops the output.
 //!
 //! ## Recursive poll/shutdown
@@ -241,7 +241,7 @@ pub(crate) struct LocalNotified<S: 'static> {
     _not_send: PhantomData<*const ()>,
 }
 
-/// A task that is not owned by any OwnedTasks. Used for blocking tasks.
+/// A task that is not owned by any `OwnedTasks`. Used for blocking tasks.
 /// This type holds two ref-counts.
 pub(crate) struct UnownedTask<S: 'static> {
     raw: RawTask,
@@ -280,7 +280,7 @@ pub(crate) trait Schedule: Sync + Sized + 'static {
 
 cfg_rt! {
     /// This is the constructor for a new task. Three references to the task are
-    /// created. The first task reference is usually put into an OwnedTasks
+    /// created. The first task reference is usually put into an `OwnedTasks`
     /// immediately. The Notified is sent to the scheduler as an ordinary
     /// notification.
     fn new_task<T, S>(

tokio/src/runtime/task/state.rs

@@ -53,9 +53,9 @@ const REF_ONE: usize = 1 << REF_COUNT_SHIFT;
 ///
 /// A task is initialized with three references:
 ///
-///  * A reference that will be stored in an OwnedTasks or LocalOwnedTasks.
+///  * A reference that will be stored in an `OwnedTasks` or `LocalOwnedTasks`.
 ///  * A reference that will be sent to the scheduler as an ordinary notification.
-///  * A reference for the JoinHandle.
+///  * A reference for the `JoinHandle`.
 ///
 /// As the task starts with a `JoinHandle`, `JOIN_INTEREST` is set.
 /// As the task starts with a `Notified`, `NOTIFIED` is set.

tokio/src/runtime/task/trace/mod.rs

@@ -265,7 +265,7 @@ impl<T: Future> Future for Root<T> {
     }
 }
 
-/// Trace and poll all tasks of the current_thread runtime.
+/// Trace and poll all tasks of the `current_thread` runtime.
 pub(in crate::runtime) fn trace_current_thread(
     owned: &OwnedTasks<Arc<current_thread::Handle>>,
     local: &mut VecDeque<Notified<Arc<current_thread::Handle>>>,
@@ -293,7 +293,7 @@ cfg_rt_multi_thread! {
     use crate::runtime::scheduler::multi_thread::Synced;
     use crate::runtime::scheduler::inject::Shared;
 
-    /// Trace and poll all tasks of the current_thread runtime.
+    /// Trace and poll all tasks of the `current_thread` runtime.
     ///
     /// ## Safety
     ///

tokio/src/runtime/tests/loom_local.rs

@@ -9,7 +9,7 @@ use std::task::Poll;
 /// to the runtime itself. This means that if they are not properly removed at
 /// runtime shutdown, this will cause a memory leak.
 ///
-/// This test verifies that waking something during shutdown of a LocalSet does
+/// This test verifies that waking something during shutdown of a `LocalSet` does
 /// not result in tasks lingering in the queue once shutdown is complete. This
 /// is verified using loom's leak finder.
 #[test]

tokio/src/runtime/time/entry.rs

@@ -11,10 +11,10 @@
 //! 2) a held driver lock.
 //!
 //! It follows from this that any changes made while holding BOTH 1 and 2 will
-//! be reliably visible, regardless of ordering. This is because of the acq/rel
+//! be reliably visible, regardless of ordering. This is because of the `acq/rel`
 //! fences on the driver lock ensuring ordering with 2, and rust mutable
 //! reference rules for 1 (a mutable reference to an object can't be passed
-//! between threads without an acq/rel barrier, and same-thread we have local
+//! between threads without an `acq/rel` barrier, and same-thread we have local
 //! happens-before ordering).
 //!
 //! # State field
@@ -81,12 +81,12 @@ pub(super) const MAX_SAFE_MILLIS_DURATION: u64 = u64::MAX - 2;
 /// time (if registered), or otherwise the result of the timer completing, as
 /// well as the registered waker.
 ///
-/// Generally, the StateCell is only permitted to be accessed from two contexts:
-/// Either a thread holding the corresponding &mut TimerEntry, or a thread
-/// holding the timer driver lock. The write actions on the StateCell amount to
-/// passing "ownership" of the StateCell between these contexts; moving a timer
-/// from the TimerEntry to the driver requires _both_ holding the &mut
-/// TimerEntry and the driver lock, while moving it back (firing the timer)
+/// Generally, the `StateCell` is only permitted to be accessed from two contexts:
+/// Either a thread holding the corresponding `&mut TimerEntry`, or a thread
+/// holding the timer driver lock. The write actions on the `StateCell` amount to
+/// passing "ownership" of the `StateCell` between these contexts; moving a timer
+/// from the `TimerEntry` to the driver requires _both_ holding the `&mut
+/// TimerEntry` and the driver lock, while moving it back (firing the timer)
 /// requires only the driver lock.
 pub(super) struct StateCell {
     /// Holds either the scheduled expiration time for this timer, or (if the
@@ -164,7 +164,7 @@ impl StateCell {
     /// Marks this timer as being moved to the pending list, if its scheduled
     /// time is not after `not_after`.
     ///
-    /// If the timer is scheduled for a time after not_after, returns an Err
+    /// If the timer is scheduled for a time after `not_after`, returns an Err
     /// containing the current scheduled time.
     ///
     /// SAFETY: Must hold the driver lock.
@@ -314,15 +314,15 @@ pub(crate) struct TimerEntry {
 unsafe impl Send for TimerEntry {}
 unsafe impl Sync for TimerEntry {}
 
-/// An TimerHandle is the (non-enforced) "unique" pointer from the driver to the
-/// timer entry. Generally, at most one TimerHandle exists for a timer at a time
+/// An `TimerHandle` is the (non-enforced) "unique" pointer from the driver to the
+/// timer entry. Generally, at most one `TimerHandle` exists for a timer at a time
 /// (enforced by the timer state machine).
 ///
-/// SAFETY: An TimerHandle is essentially a raw pointer, and the usual caveats
-/// of pointer safety apply. In particular, TimerHandle does not itself enforce
-/// that the timer does still exist; however, normally an TimerHandle is created
+/// SAFETY: An `TimerHandle` is essentially a raw pointer, and the usual caveats
+/// of pointer safety apply. In particular, `TimerHandle` does not itself enforce
+/// that the timer does still exist; however, normally an `TimerHandle` is created
 /// immediately before registering the timer, and is consumed when firing the
-/// timer, to help minimize mistakes. Still, because TimerHandle cannot enforce
+/// timer, to help minimize mistakes. Still, because `TimerHandle` cannot enforce
 /// memory safety, all operations are unsafe.
 #[derive(Debug)]
 pub(crate) struct TimerHandle {
@@ -437,7 +437,7 @@ impl TimerShared {
         self.state.extend_expiration(t)
     }
 
-    /// Returns a TimerHandle for this timer.
+    /// Returns a `TimerHandle` for this timer.
     pub(super) fn handle(&self) -> TimerHandle {
         TimerHandle {
             inner: NonNull::from(self),

tokio/src/runtime/time/source.rs

@@ -1,7 +1,7 @@
 use super::MAX_SAFE_MILLIS_DURATION;
 use crate::time::{Clock, Duration, Instant};
 
-/// A structure which handles conversion from Instants to u64 timestamps.
+/// A structure which handles conversion from Instants to `u64` timestamps.
 #[derive(Debug)]
 pub(crate) struct TimeSource {
     start_time: Instant,

tokio/src/runtime/time/wheel/level.rs

@@ -15,7 +15,7 @@ pub(crate) struct Level {
     /// The least-significant bit represents slot zero.
     occupied: u64,
 
-    /// Slots. We access these via the EntryInner `current_list` as well, so this needs to be an UnsafeCell.
+    /// Slots. We access these via the EntryInner `current_list` as well, so this needs to be an `UnsafeCell`.
     slot: [EntryList; LEVEL_MULT],
 }
 

tokio/src/signal/ctrl_c.rs

@@ -23,10 +23,10 @@ use std::io;
 /// the entire process**.
 ///
 /// For example, Unix systems will terminate a process by default when it
-/// receives a signal generated by "CTRL+C" on the terminal. But, when a
+/// receives a signal generated by `"CTRL+C"` on the terminal. But, when a
 /// `ctrl_c` stream is created to listen for this signal, the time it arrives,
 /// it will be translated to a stream event, and the process will continue to
-/// execute.  **Even if this `Signal` instance is dropped, subsequent SIGINT
+/// execute.  **Even if this `Signal` instance is dropped, subsequent `SIGINT`
 /// deliveries will end up captured by Tokio, and the default platform behavior
 /// will NOT be reset**.
 ///

tokio/src/signal/mod.rs

@@ -23,7 +23,7 @@
 //! }
 //! ```
 //!
-//! Wait for SIGHUP on Unix
+//! Wait for `SIGHUP` on Unix
 //!
 //! ```rust,no_run
 //! # #[cfg(unix)] {

tokio/src/signal/registry.rs

@@ -26,7 +26,7 @@ impl Default for EventInfo {
     }
 }
 
-/// An interface for retrieving the `EventInfo` for a particular eventId.
+/// An interface for retrieving the `EventInfo` for a particular `eventId`.
 pub(crate) trait Storage {
     /// Gets the `EventInfo` for `id` if it exists.
     fn event_info(&self, id: EventId) -> Option<&EventInfo>;
@@ -59,7 +59,7 @@ pub(crate) trait Init {
 /// Manages and distributes event notifications to any registered listeners.
 ///
 /// Generic over the underlying storage to allow for domain specific
-/// optimizations (e.g. eventIds may or may not be contiguous).
+/// optimizations (e.g. `eventIds` may or may not be contiguous).
 #[derive(Debug)]
 pub(crate) struct Registry<S> {
     storage: S,

tokio/src/signal/unix.rs

@@ -97,7 +97,7 @@ impl SignalKind {
         self.0
     }
 
-    /// Represents the SIGALRM signal.
+    /// Represents the `SIGALRM` signal.
     ///
     /// On Unix systems this signal is sent when a real-time timer has expired.
     /// By default, the process is terminated by this signal.
@@ -105,7 +105,7 @@ impl SignalKind {
         Self(libc::SIGALRM)
     }
 
-    /// Represents the SIGCHLD signal.
+    /// Represents the `SIGCHLD` signal.
     ///
     /// On Unix systems this signal is sent when the status of a child process
     /// has changed. By default, this signal is ignored.
@@ -113,7 +113,7 @@ impl SignalKind {
         Self(libc::SIGCHLD)
     }
 
-    /// Represents the SIGHUP signal.
+    /// Represents the `SIGHUP` signal.
     ///
     /// On Unix systems this signal is sent when the terminal is disconnected.
     /// By default, the process is terminated by this signal.
@@ -121,7 +121,7 @@ impl SignalKind {
         Self(libc::SIGHUP)
     }
 
-    /// Represents the SIGINFO signal.
+    /// Represents the `SIGINFO` signal.
     ///
     /// On Unix systems this signal is sent to request a status update from the
     /// process. By default, this signal is ignored.
@@ -136,7 +136,7 @@ impl SignalKind {
         Self(libc::SIGINFO)
     }
 
-    /// Represents the SIGINT signal.
+    /// Represents the `SIGINT` signal.
     ///
     /// On Unix systems this signal is sent to interrupt a program.
     /// By default, the process is terminated by this signal.
@@ -144,7 +144,7 @@ impl SignalKind {
         Self(libc::SIGINT)
     }
 
-    /// Represents the SIGIO signal.
+    /// Represents the `SIGIO` signal.
     ///
     /// On Unix systems this signal is sent when I/O operations are possible
     /// on some file descriptor. By default, this signal is ignored.
@@ -152,7 +152,7 @@ impl SignalKind {
         Self(libc::SIGIO)
     }
 
-    /// Represents the SIGPIPE signal.
+    /// Represents the `SIGPIPE` signal.
     ///
     /// On Unix systems this signal is sent when the process attempts to write
     /// to a pipe which has no reader. By default, the process is terminated by
@@ -161,7 +161,7 @@ impl SignalKind {
         Self(libc::SIGPIPE)
     }
 
-    /// Represents the SIGQUIT signal.
+    /// Represents the `SIGQUIT` signal.
     ///
     /// On Unix systems this signal is sent to issue a shutdown of the
     /// process, after which the OS will dump the process core.
@@ -170,7 +170,7 @@ impl SignalKind {
         Self(libc::SIGQUIT)
     }
 
-    /// Represents the SIGTERM signal.
+    /// Represents the `SIGTERM` signal.
     ///
     /// On Unix systems this signal is sent to issue a shutdown of the
     /// process. By default, the process is terminated by this signal.
@@ -178,7 +178,7 @@ impl SignalKind {
         Self(libc::SIGTERM)
     }
 
-    /// Represents the SIGUSR1 signal.
+    /// Represents the `SIGUSR1` signal.
     ///
     /// On Unix systems this is a user defined signal.
     /// By default, the process is terminated by this signal.
@@ -186,7 +186,7 @@ impl SignalKind {
         Self(libc::SIGUSR1)
     }
 
-    /// Represents the SIGUSR2 signal.
+    /// Represents the `SIGUSR2` signal.
     ///
     /// On Unix systems this is a user defined signal.
     /// By default, the process is terminated by this signal.
@@ -194,7 +194,7 @@ impl SignalKind {
         Self(libc::SIGUSR2)
     }
 
-    /// Represents the SIGWINCH signal.
+    /// Represents the `SIGWINCH` signal.
     ///
     /// On Unix systems this signal is sent when the terminal window is resized.
     /// By default, this signal is ignored.
@@ -330,10 +330,10 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> {
 /// entire process**.
 ///
 /// For example, Unix systems will terminate a process by default when it
-/// receives SIGINT. But, when a `Signal` instance is created to listen for
-/// this signal, the next SIGINT that arrives will be translated to a stream
+/// receives `SIGINT`. But, when a `Signal` instance is created to listen for
+/// this signal, the next `SIGINT` that arrives will be translated to a stream
 /// event, and the process will continue to execute. **Even if this `Signal`
-/// instance is dropped, subsequent SIGINT deliveries will end up captured by
+/// instance is dropped, subsequent `SIGINT` deliveries will end up captured by
 /// Tokio, and the default platform behavior will NOT be reset**.
 ///
 /// Thus, applications should take care to ensure the expected signal behavior
@@ -341,7 +341,7 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> {
 ///
 /// # Examples
 ///
-/// Wait for SIGHUP
+/// Wait for `SIGHUP`
 ///
 /// ```rust,no_run
 /// use tokio::signal::unix::{signal, SignalKind};
@@ -424,7 +424,7 @@ impl Signal {
     ///
     /// # Examples
     ///
-    /// Wait for SIGHUP
+    /// Wait for `SIGHUP`
     ///
     /// ```rust,no_run
     /// use tokio::signal::unix::{signal, SignalKind};

tokio/src/signal/windows.rs

@@ -3,7 +3,7 @@
 //! This module is only defined on Windows and allows receiving "ctrl-c",
 //! "ctrl-break", "ctrl-logoff", "ctrl-shutdown", and "ctrl-close"
 //! notifications. These events are listened for via the `SetConsoleCtrlHandler`
-//! function which receives the corresponding windows_sys event type.
+//! function which receives the corresponding `windows_sys` event type.
 
 #![cfg(any(windows, docsrs))]
 #![cfg_attr(docsrs, doc(cfg(all(windows, feature = "signal"))))]
@@ -257,8 +257,8 @@ pub fn ctrl_close() -> io::Result<CtrlClose> {
     })
 }
 
-/// Represents a listener which receives "ctrl-close" notitifications sent to the process
-/// via 'SetConsoleCtrlHandler'.
+/// Represents a listener which receives "ctrl-close" notifications sent to the process
+/// via `SetConsoleCtrlHandler`.
 ///
 /// A notification to this process notifies *all* listeners listening for
 /// this event. Moreover, the notifications **are coalesced** if they aren't processed
@@ -354,8 +354,8 @@ pub fn ctrl_shutdown() -> io::Result<CtrlShutdown> {
     })
 }
 
-/// Represents a listener which receives "ctrl-shutdown" notitifications sent to the process
-/// via 'SetConsoleCtrlHandler'.
+/// Represents a listener which receives "ctrl-shutdown" notifications sent to the process
+/// via `SetConsoleCtrlHandler`.
 ///
 /// A notification to this process notifies *all* listeners listening for
 /// this event. Moreover, the notifications **are coalesced** if they aren't processed
@@ -451,8 +451,8 @@ pub fn ctrl_logoff() -> io::Result<CtrlLogoff> {
     })
 }
 
-/// Represents a listener which receives "ctrl-logoff" notitifications sent to the process
-/// via 'SetConsoleCtrlHandler'.
+/// Represents a listener which receives "ctrl-logoff" notifications sent to the process
+/// via `SetConsoleCtrlHandler`.
 ///
 /// A notification to this process notifies *all* listeners listening for
 /// this event. Moreover, the notifications **are coalesced** if they aren't processed

tokio/src/sync/mpsc/error.rs

@@ -24,7 +24,7 @@ impl<T> Error for SendError<T> {}
 // ===== TrySendError =====
 
 /// This enumeration is the list of the possible error outcomes for the
-/// [try_send](super::Sender::try_send) method.
+/// [`try_send`](super::Sender::try_send) method.
 #[derive(PartialEq, Eq, Clone, Copy)]
 pub enum TrySendError<T> {
     /// The data could not be sent on the channel because the channel is

tokio/src/sync/oneshot.rs

@@ -59,7 +59,7 @@
 //! }
 //! ```
 //!
-//! To use a oneshot channel in a `tokio::select!` loop, add `&mut` in front of
+//! To use a `oneshot` channel in a `tokio::select!` loop, add `&mut` in front of
 //! the channel.
 //!
 //! ```
@@ -330,7 +330,7 @@ pub struct Receiver<T> {
 }
 
 pub mod error {
-    //! Oneshot error types.
+    //! `Oneshot` error types.
 
     use std::fmt;
 
@@ -555,8 +555,8 @@ impl<T> Sender<T> {
     /// Attempts to send a value on this channel, returning it back if it could
     /// not be sent.
     ///
-    /// This method consumes `self` as only one value may ever be sent on a oneshot
-    /// channel. It is not marked async because sending a message to an oneshot
+    /// This method consumes `self` as only one value may ever be sent on a `oneshot`
+    /// channel. It is not marked async because sending a message to an `oneshot`
     /// channel never requires any form of waiting.  Because of this, the `send`
     /// method can be used in both synchronous and asynchronous code without
     /// problems.
@@ -750,7 +750,7 @@ impl<T> Sender<T> {
         state.is_closed()
     }
 
-    /// Checks whether the oneshot channel has been closed, and if not, schedules the
+    /// Checks whether the `oneshot` channel has been closed, and if not, schedules the
     /// `Waker` in the provided `Context` to receive a notification when the channel is
     /// closed.
     ///

tokio/src/task/local.rs

@@ -237,7 +237,7 @@ struct Context {
     unhandled_panic: Cell<bool>,
 }
 
-/// LocalSet state shared between threads.
+/// `LocalSet` state shared between threads.
 struct Shared {
     /// # Safety
     ///
@@ -290,7 +290,7 @@ struct LocalData {
 
 impl LocalData {
     /// Should be called except when we call `LocalSet::enter`.
-    /// Especially when we poll a LocalSet.
+    /// Especially when we poll a `LocalSet`.
     #[must_use = "dropping this guard will reset the entered state"]
     fn enter(&self, ctx: Rc<Context>) -> LocalDataEnterGuard<'_> {
         let ctx = self.ctx.replace(Some(ctx));
@@ -392,7 +392,7 @@ const MAX_TASKS_PER_TICK: usize = 61;
 /// How often it check the remote queue first.
 const REMOTE_FIRST_INTERVAL: u8 = 31;
 
-/// Context guard for LocalSet
+/// Context guard for `LocalSet`
 pub struct LocalEnterGuard {
     ctx: Option<Rc<Context>>,
 
@@ -526,7 +526,7 @@ impl LocalSet {
     /// This runs the given future on the runtime, blocking until it is
     /// complete, and yielding its resolved result. Any tasks or timers which
     /// the future spawns internally will be executed on the runtime. The future
-    /// may also call [`spawn_local`] to spawn_local additional local futures on the
+    /// may also call [`spawn_local`] to `spawn_local` additional local futures on the
     /// current thread.
     ///
     /// This method should not be called from an asynchronous context.

tokio/src/task/mod.rs

@@ -5,8 +5,8 @@
 //! A _task_ is a light weight, non-blocking unit of execution. A task is similar
 //! to an OS thread, but rather than being managed by the OS scheduler, they are
 //! managed by the [Tokio runtime][rt]. Another name for this general pattern is
-//! [green threads]. If you are familiar with [Go's goroutines], [Kotlin's
-//! coroutines], or [Erlang's processes], you can think of Tokio's tasks as
+//! [green threads]. If you are familiar with [`Go's goroutines`], [`Kotlin's
+//! coroutines`], or [`Erlang's processes`], you can think of Tokio's tasks as
 //! something similar.
 //!
 //! Key points about tasks include:
@@ -167,7 +167,7 @@
 //! blocking operations there. This includes destructors of objects destroyed in
 //! async code.
 //!
-//! #### spawn_blocking
+//! #### `spawn_blocking`
 //!
 //! The `task::spawn_blocking` function is similar to the `task::spawn` function
 //! discussed in the previous section, but rather than spawning an
@@ -202,7 +202,7 @@
 //! # }
 //! ```
 //!
-//! #### block_in_place
+//! #### `block_in_place`
 //!
 //! When using the [multi-threaded runtime][rt-multi-thread], the [`task::block_in_place`]
 //! function is also available. Like `task::spawn_blocking`, this function
@@ -227,7 +227,7 @@
 //! # }
 //! ```
 //!
-//! #### yield_now
+//! #### `yield_now`
 //!
 //! In addition, this module provides a [`task::yield_now`] async function
 //! that is analogous to the standard library's [`thread::yield_now`]. Calling

tokio/src/util/idle_notified_set.rs

@@ -42,8 +42,8 @@ pub(crate) struct EntryInOneOfTheLists<'a, T> {
 
 type Lists<T> = Mutex<ListsInner<T>>;
 
-/// The linked lists hold strong references to the ListEntry items, and the
-/// ListEntry items also hold a strong reference back to the Lists object, but
+/// The linked lists hold strong references to the `ListEntry` items, and the
+/// `ListEntry` items also hold a strong reference back to the Lists object, but
 /// the destructor of the `IdleNotifiedSet` will clear the two lists, so once
 /// that object is destroyed, no ref-cycles will remain.
 struct ListsInner<T> {

tokio/src/util/rand.rs

@@ -20,9 +20,9 @@ pub struct RngSeed {
 
 /// Fast random number generate.
 ///
-/// Implement xorshift64+: 2 32-bit xorshift sequences added together.
+/// Implement `xorshift64+`: 2 32-bit `xorshift` sequences added together.
 /// Shift triplet `[17,7,16]` was calculated as indicated in Marsaglia's
-/// Xorshift paper: <https://www.jstatsoft.org/article/view/v008i14/xorshift.pdf>
+/// `Xorshift` paper: <https://www.jstatsoft.org/article/view/v008i14/xorshift.pdf>
 /// This generator passes the SmallCrush suite, part of TestU01 framework:
 /// <http://simul.iro.umontreal.ca/testu01/tu01.html>
 #[derive(Clone, Copy, Debug)]

tokio/src/util/sharded_list.rs

@@ -56,7 +56,7 @@ pub(crate) struct ShardGuard<'a, L, T> {
 }
 
 impl<L: ShardedListItem> ShardedList<L, L::Target> {
-    /// Removes the last element from a list specified by shard_id and returns it, or None if it is
+    /// Removes the last element from a list specified by `shard_id` and returns it, or None if it is
     /// empty.
     pub(crate) fn pop_back(&self, shard_id: usize) -> Option<L::Handle> {
         let mut lock = self.shard_inner(shard_id);
@@ -87,7 +87,7 @@ impl<L: ShardedListItem> ShardedList<L, L::Target> {
         node
     }
 
-    /// Gets the lock of ShardedList, makes us have the write permission.
+    /// Gets the lock of `ShardedList`, makes us have the write permission.
     pub(crate) fn lock_shard(&self, val: &L::Handle) -> ShardGuard<'_, L, L::Target> {
         let id = unsafe { L::get_shard_id(L::as_raw(val)) };
         ShardGuard {
@@ -107,7 +107,7 @@ impl<L: ShardedListItem> ShardedList<L, L::Target> {
         self.len() == 0
     }
 
-    /// Gets the shard size of this SharedList.
+    /// Gets the shard size of this `SharedList`.
     ///
     /// Used to help us to decide the parameter `shard_id` of the `pop_back` method.
     pub(crate) fn shard_size(&self) -> usize {