Enhance the docs

src/dispatching/dispatcher.rs

@@ -102,7 +102,7 @@ where
         Some(tx)
     }
 
-    /// Setup `^C` handler which [`shutdown`]s dispatching.
+    /// Setup the `^C` handler which [`shutdown`]s dispatching.
     ///
     /// [`shutdown`]: ShutdownToken::shutdown
     #[cfg(feature = "ctrlc_handler")]
@@ -246,11 +246,12 @@ where
     /// errors produced by this listener).
     ///
     /// Please note that after shutting down (either because of [`shutdown`],
-    /// [ctrlc signal], or `update_listener` returning `None`) all handlers will
-    /// be gone. As such, to restart listening you need to re-add handlers.
+    /// [a ctrlc signal], or [`UpdateListener`] returning `None`) all handlers
+    /// will be gone. As such, to restart listening you need to re-add
+    /// handlers.
     ///
     /// [`shutdown`]: ShutdownToken::shutdown
-    /// [ctrlc signal]: Dispatcher::setup_ctrlc_handler
+    /// [a ctrlc signal]: Dispatcher::setup_ctrlc_handler
     pub async fn dispatch(&mut self)
     where
         R: Requester + Clone,
@@ -267,11 +268,12 @@ where
     /// `update_listener_error_handler`.
     ///
     /// Please note that after shutting down (either because of [`shutdown`],
-    /// [ctrlc signal], or `update_listener` returning `None`) all handlers will
-    /// be gone. As such, to restart listening you need to re-add handlers.
+    /// [a ctrlc signal], or [`UpdateListener`] returning `None`) all handlers
+    /// will be gone. As such, to restart listening you need to re-add
+    /// handlers.
     ///
     /// [`shutdown`]: ShutdownToken::shutdown
-    /// [ctrlc signal]: Dispatcher::setup_ctrlc_handler
+    /// [a ctrlc signal]: Dispatcher::setup_ctrlc_handler
     pub async fn dispatch_with_listener<'a, UListener, ListenerE, Eh>(
         &'a mut self,
         mut update_listener: UListener,
@@ -330,7 +332,8 @@ where
         self.state.store(Idle);
     }
 
-    /// Returns shutdown token, which can later be used to shutdown dispatching.
+    /// Returns a shutdown token, which can later be used to shutdown
+    /// dispatching.
     pub fn shutdown_token(&self) -> ShutdownToken {
         ShutdownToken {
             dispatcher_state: Arc::clone(&self.state),
@@ -459,7 +462,7 @@ where
 }
 
 /// This error is returned from [`ShutdownToken::shutdown`] when trying to
-/// shutdown idle dispatcher.
+/// shutdown an idle [`Dispatcher`].
 #[derive(Debug)]
 pub struct IdleShutdownError;
 
@@ -471,7 +474,7 @@ impl fmt::Display for IdleShutdownError {
 
 impl std::error::Error for IdleShutdownError {}
 
-/// A token which can be used to shutdown dispatcher.
+/// A token which used to shutdown [`Dispatcher`].
 #[derive(Clone)]
 pub struct ShutdownToken {
     dispatcher_state: Arc<DispatcherState>,
@@ -481,9 +484,10 @@ pub struct ShutdownToken {
 impl ShutdownToken {
     /// Tries to shutdown dispatching.
     ///
-    /// Returns error if this dispather is idle at the moment.
+    /// Returns an error if the dispatcher is idle at the moment.
     ///
-    /// If you don't need to wait for shutdown, returned future can be ignored.
+    /// If you don't need to wait for shutdown, the returned future can be
+    /// ignored.
     pub fn shutdown(&self) -> Result<impl Future<Output = ()> + '_, IdleShutdownError> {
         shutdown_inner(&self.dispatcher_state)
             .map(|()| async move { self.shutdown_notify_back.notified().await })

src/dispatching/stop_token.rs

@@ -1,8 +1,10 @@
+//! A stop token used to stop a listener.
+
 use std::{future::Future, pin::Pin, task};
 
 use futures::future::{pending, AbortHandle, Abortable, Pending};
 
-/// A stop token allows you to stop listener.
+/// A stop token allows you to stop a listener.
 ///
 /// See also: [`UpdateListener::stop_token`].
 ///
@@ -27,8 +29,8 @@ pub struct AsyncStopToken(AbortHandle);
 
 /// A flag which corresponds to [`AsyncStopToken`].
 ///
-/// To know if stop token was used you can either repeatedly call [`is_stopped`]
-/// or use this type as a `Future`.
+/// To know if the stop token was used you can either repeatedly call
+/// [`is_stopped`] or use this type as a `Future`.
 ///
 /// [`is_stopped`]: AsyncStopFlag::is_stopped
 #[pin_project::pin_project]
@@ -52,7 +54,7 @@ impl StopToken for AsyncStopToken {
 }
 
 impl AsyncStopFlag {
-    /// Returns true if stop token linked to `self` was used.
+    /// Returns true if the stop token linked to `self` was used.
     pub fn is_stopped(&self) -> bool {
         self.0.is_aborted()
     }

src/dispatching/update_listeners.rs

@@ -127,21 +127,19 @@ pub use self::{
 ///
 /// Some functions of this trait are located in the supertrait
 /// ([`AsUpdateStream`]), see also:
-/// - [`Stream`]
-/// - [`as_stream`]
+/// - [`AsUpdateStream::Stream`]
+/// - [`AsUpdateStream::as_stream`]
 ///
 /// [polling]: self#long-polling
 /// [webhooks]: self#webhooks
-/// [`Stream`]: AsUpdateStream::Stream
-/// [`as_stream`]: AsUpdateStream::as_stream
 pub trait UpdateListener<E>: for<'a> AsUpdateStream<'a, E> {
-    /// Type of token which allows ti stop this listener.
+    /// The type of token which allows to stop this listener.
     type StopToken: StopToken;
 
     /// Returns a token which stops this listener.
     ///  
     /// The [`stop`] function of the token is not guaranteed to have an
-    /// immediate effect. That is some listeners can return updates even
+    /// immediate effect. That is, some listeners can return updates even
     /// after [`stop`] is called (e.g.: because of buffering).
     ///
     /// [`stop`]: StopToken::stop
@@ -153,15 +151,15 @@ pub trait UpdateListener<E>: for<'a> AsUpdateStream<'a, E> {
                   the returned token"]
     fn stop_token(&mut self) -> Self::StopToken;
 
-    /// Timeout duration hint.
+    /// The timeout duration hint.
     ///
-    /// This hints how often dispatcher should check for shutdown. E.g. for
+    /// This hints how often dispatcher should check for a shutdown. E.g., for
     /// [`polling()`] this returns the [`timeout`].
     ///
     /// [`timeout`]: crate::payloads::GetUpdates::timeout
     ///
     /// If you are implementing this trait and not sure what to return from this
-    /// function, just leave it with default implementation.
+    /// function, just leave it with the default implementation.
     fn timeout_hint(&self) -> Option<Duration> {
         None
     }
@@ -171,7 +169,7 @@ pub trait UpdateListener<E>: for<'a> AsUpdateStream<'a, E> {
 ///
 /// This trait is a workaround to not require GAT.
 pub trait AsUpdateStream<'a, E> {
-    /// Stream of updates from Telegram.
+    /// The stream of updates from Telegram.
     type Stream: Stream<Item = Result<Update, E>> + 'a;
 
     /// Creates the update [`Stream`].

src/dispatching/update_listeners/stateful_listener.rs

@@ -10,10 +10,10 @@ use crate::dispatching::{
 
 /// A listener created from functions.
 ///
-/// This type allows to turn a stream of updates (+some additional functions)
+/// This type allows to turn a stream of updates (+ some additional functions)
 /// into an [`UpdateListener`].
 ///
-/// For an example of usage see [`polling`]
+/// For an example of usage, see [`polling`].
 ///
 /// [`polling`]: crate::dispatching::update_listeners::polling()
 #[non_exhaustive]
@@ -21,18 +21,18 @@ pub struct StatefulListener<St, Assf, Sf, Thf> {
     /// The state of the listener.
     pub state: St,
 
-    /// Function used as [`AsUpdateStream::as_stream`].
+    /// The function used as [`AsUpdateStream::as_stream`].
     ///
     /// Must be of type `for<'a> &'a mut St -> impl Stream + 'a` and callable by
     /// `&mut`.
     pub stream: Assf,
 
-    /// Function used as [`UpdateListener::stop_token`].
+    /// The function used as [`UpdateListener::stop_token`].
     ///
     /// Must be of type `for<'a> &'a mut St -> impl StopToken`.
     pub stop_token: Sf,
 
-    /// Function used as [`UpdateListener::timeout_hint`].
+    /// The function used as [`UpdateListener::timeout_hint`].
     ///
     /// Must be of type `for<'a> &'a St -> Option<Duration>` and callable by
     /// `&`.
@@ -40,14 +40,14 @@ pub struct StatefulListener<St, Assf, Sf, Thf> {
 }
 
 impl<St, Assf, Sf> StatefulListener<St, Assf, Sf, for<'a> fn(&'a St) -> Option<Duration>> {
-    /// Creates new stateful listener from it's components.
+    /// Creates a new stateful listener from its components.
     pub fn new(state: St, stream: Assf, stop_token: Sf) -> Self {
         Self { state, stream, stop_token, timeout_hint: None }
     }
 }
 
 impl<St, Assf, Sf, Thf> StatefulListener<St, Assf, Sf, Thf> {
-    /// Creates new stateful listener from it's components.
+    /// Creates a new stateful listener from its components.
     pub fn new_with_timeout_hint(
         state: St,
         stream: Assf,
@@ -68,10 +68,10 @@ impl<S, E>
 where
     S: Stream<Item = Result<Update, E>> + Unpin + 'static,
 {
-    /// Creates a new update listner from a stream of updates which ignore stop
-    /// signals.
+    /// Creates a new update listener from a stream of updates which ignores
+    /// stop signals.
     ///
-    /// It won't be possible to ever stop this listener with stop token.
+    /// It won't be possible to ever stop this listener with a stop token.
     pub fn from_stream_without_graceful_shutdown(stream: S) -> Self {
         let this = Self {
             state: stream,