diff --git a/src/dispatching/dispatcher.rs b/src/dispatching/dispatcher.rs index 88c3aa1b..5dd64783 100644 --- a/src/dispatching/dispatcher.rs +++ b/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, @@ -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 + '_, IdleShutdownError> { shutdown_inner(&self.dispatcher_state) .map(|()| async move { self.shutdown_notify_back.notified().await }) diff --git a/src/dispatching/stop_token.rs b/src/dispatching/stop_token.rs index faea1ed2..4198d4c0 100644 --- a/src/dispatching/stop_token.rs +++ b/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() } diff --git a/src/dispatching/update_listeners.rs b/src/dispatching/update_listeners.rs index b8448023..3e2b1316 100644 --- a/src/dispatching/update_listeners.rs +++ b/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: 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: 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 { None } @@ -171,7 +169,7 @@ pub trait UpdateListener: 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> + 'a; /// Creates the update [`Stream`]. diff --git a/src/dispatching/update_listeners/stateful_listener.rs b/src/dispatching/update_listeners/stateful_listener.rs index b7a243c6..ac1f8655 100644 --- a/src/dispatching/update_listeners/stateful_listener.rs +++ b/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 { /// 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` and callable by /// `&`. @@ -40,14 +40,14 @@ pub struct StatefulListener { } impl StatefulListener fn(&'a St) -> Option> { - /// 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 StatefulListener { - /// 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 where S: Stream> + 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,