Document some stuff

src/dispatching2/filter_ext.rs

@@ -2,24 +2,26 @@ use dptree::{di::DependencyMap, Handler};
 use teloxide_core::types::{Message, Update, UpdateKind};
 
 macro_rules! define_ext {
-    ($ext_name:ident, $for_ty:ty => $( ($func:ident, $arg_ty:ty, $proj_fn:expr) ,)*) => {
+    ($ext_name:ident, $for_ty:ty => $( ($func:ident, $proj_fn:expr, $fn_doc:expr) ,)*) => {
+        #[doc = concat!("Filter methods for [`", stringify!($for_ty), "`].")]
         pub trait $ext_name<Out> {
-            $( define_ext!(@sig $func, $arg_ty); )*
+            $( define_ext!(@sig $func, $fn_doc); )*
         }
 
         impl<Out> $ext_name<Out> for $for_ty
         where
             Out: Send + Sync + 'static,
         {
-            $( define_ext!(@impl $for_ty, $func, $arg_ty, $proj_fn); )*
+            $( define_ext!(@impl $for_ty, $func, $proj_fn); )*
         }
     };
 
-    (@sig $func:ident, $arg_ty:ty) => {
+    (@sig $func:ident, $fn_doc:expr) => {
+        #[doc = $fn_doc]
         fn $func() -> Handler<'static, DependencyMap, Out>;
     };
 
-    (@impl $for_ty:ty, $func:ident, $arg_ty:ty, $proj_fn:expr) => {
+    (@impl $for_ty:ty, $func:ident, $proj_fn:expr) => {
         fn $func() -> Handler<'static, DependencyMap, Out> {
             dptree::filter_map(move |input: $for_ty| {
                 async move { $proj_fn(input) }
@@ -28,55 +30,68 @@ macro_rules! define_ext {
     };
 }
 
-macro_rules! to_owned_fn {
+macro_rules! define_message_ext {
-    ($fn_name:expr) => {
+    ($( ($func:ident, $fn_name:path) ,)*) => {
-        |x| $fn_name(&x).map(ToOwned::to_owned)
+        define_ext! {
-    };
+            MessageFilterExt, crate::types::Message =>
+            $((
+                $func,
+                (|x| $fn_name(&x).map(ToOwned::to_owned)),
+                concat!("Applies the [`crate::types::", stringify!($fn_name), "`] filter.")
+            ),)*
+        }
+    }
 }
 
 // May be expanded in the future.
-define_ext! {
+define_message_ext! {
-    MessageFilterExt, Message =>
+    (filter_from, Message::from),
-    (filter_from, types::User, to_owned_fn![Message::from]),
+    (filter_animation, Message::animation),
-    (filter_animation, types::Animation, to_owned_fn![Message::animation]),
+    (filter_audio, Message::audio),
-    (filter_audio, types::Audio, to_owned_fn![Message::audio]),
+    (filter_contact, Message::contact),
-    (filter_contact, types::Contact, to_owned_fn![Message::contact]),
+    (filter_document, Message::document),
-    (filter_document, types::Document, to_owned_fn![Message::document]),
+    (filter_location, Message::location),
-    (filter_location, types::Location, to_owned_fn![Message::location]),
+    (filter_photo, Message::photo),
-    (filter_photo, [types::PhotoSize], to_owned_fn![Message::photo]),
+    (filter_poll, Message::poll),
-    (filter_poll, types::Poll, to_owned_fn![Message::poll]),
+    (filter_sticker, Message::sticker),
-    (filter_sticker, types::Sticker, to_owned_fn![Message::sticker]),
+    (filter_text, Message::text),
-    (filter_text, str, to_owned_fn![Message::text]),
+    (filter_reply_to_message, Message::reply_to_message),
-    (filter_reply_to_message, Message, to_owned_fn![Message::reply_to_message]),
+    (filter_forward_from, Message::forward_from),
-    (filter_forward_from, types::ForwardedFrom, to_owned_fn![Message::forward_from]),
+    (filter_new_chat_members, Message::new_chat_members),
-    (filter_new_chat_members, [types::User], to_owned_fn![Message::new_chat_members]),
+    (filter_left_chat_member, Message::left_chat_member),
-    (filter_left_chat_member, types::User, to_owned_fn![Message::left_chat_member]),
+    (filter_pinned, Message::pinned_message),
-    (filter_pinned, Message, to_owned_fn![Message::pinned_message]),
+    (filter_dice, Message::dice),
-    (filter_dice, types::Dice, to_owned_fn![Message::dice]),
 }
 
-macro_rules! kind {
+macro_rules! define_update_ext {
-    ($kind:ident) => {
+    ($( ($func:ident, $kind:path) ,)*) => {
-        |update: Update| match update.kind {
+        define_ext! {
-            UpdateKind::$kind(x) => Some(x),
+            UpdateFilterExt, crate::types::Update =>
-            _ => None,
+            $((
+                $func,
+                |update: Update| match update.kind {
+                    $kind(x) => Some(x),
+                    _ => None,
+                },
+                concat!("Filters out [`crate::types::", stringify!($kind), "`] objects.")
+            ),)*
         }
-    };
+    }
 }
 
-define_ext! {
+// May be expanded in the future.
-    UpdateFilterExt, Update =>
+define_update_ext! {
-    (filter_message, types::Message, kind![Message]),
+    (filter_message, UpdateKind::Message),
-    (filter_edited_message, types::EditedMessage, kind![EditedMessage]),
+    (filter_edited_message, UpdateKind::EditedMessage),
-    (filter_channel_post, types::ChannelPost, kind![ChannelPost]),
+    (filter_channel_post, UpdateKind::ChannelPost),
-    (filter_edited_channel_post, types::EditedChannelPost, kind![EditedChannelPost]),
+    (filter_edited_channel_post, UpdateKind::EditedChannelPost),
-    (filter_inline_query, types::InlineQuery, kind![InlineQuery]),
+    (filter_inline_query, UpdateKind::InlineQuery),
-    (filter_chosen_inline_result, types::ChosenInlineResult, kind![ChosenInlineResult]),
+    (filter_chosen_inline_result, UpdateKind::ChosenInlineResult),
-    (filter_callback_query, types::CallbackQuery, kind![CallbackQuery]),
+    (filter_callback_query, UpdateKind::CallbackQuery),
-    (filter_shipping_query, types::ShippingQuery, kind![ShippingQuery]),
+    (filter_shipping_query, UpdateKind::ShippingQuery),
-    (filter_pre_checkout_query, types::PreCheckoutQuery, kind![PreCheckoutQuery]),
+    (filter_pre_checkout_query, UpdateKind::PreCheckoutQuery),
-    (filter_poll, types::Poll, kind![Poll]),
+    (filter_poll, UpdateKind::Poll),
-    (filter_poll_answer, types::PollAnswer, kind![PollAnswer]),
+    (filter_poll_answer, UpdateKind::PollAnswer),
-    (filter_my_chat_member, types::MyChatMember, kind![MyChatMember]),
+    (filter_my_chat_member, UpdateKind::MyChatMember),
-    (filter_chat_member, types::ChatMember, kind![ChatMember]),
+    (filter_chat_member, UpdateKind::ChatMember),
 }

src/dispatching2/handler_ext.rs

@@ -1,8 +1,18 @@
-use crate::{dispatching2::HandlerFactory, types::Message, utils::command::BotCommand};
+use crate::{
+    dispatching2::HandlerFactory,
+    types::{Me, Message},
+    utils::command::BotCommand,
+};
 use dptree::{di::DependencyMap, Handler};
-use teloxide_core::types::Me;
 
+/// Extension methods for working with `dptree` handlers.
 pub trait HandlerExt<Output> {
+    /// Returns a handler that accepts a parsed command `C`.
+    ///
+    /// ## Dependency requirements
+    ///
+    ///  - [`crate::types::Message`]
+    ///  - [`crate::types::Me`]
     #[must_use]
     fn add_command<C>(self) -> Self
     where

src/dispatching2/repls/commands_repl.rs

@@ -13,11 +13,15 @@ use teloxide_core::requests::Requester;
 ///
 /// All errors from an update listener and handler will be logged.
 ///
-/// # Caution
+/// ## Caution
 /// **DO NOT** use this function together with [`Dispatcher`] and other REPLs,
 /// because Telegram disallow multiple requests at the same time from the same
 /// bot.
 ///
+/// ## Dependency requirements
+///
+///  - Those of [`HandlerExt::add_command`].
+///
 /// [REPL]: https://en.wikipedia.org/wiki/Read-eval-print_loop
 /// [`Dispatcher`]: crate::dispatching::Dispatcher
 #[cfg(feature = "ctrlc_handler")]
@@ -44,11 +48,15 @@ where
 ///
 /// All errors from an update listener and handler will be logged.
 ///
-/// # Caution
+/// ## Caution
 /// **DO NOT** use this function together with [`Dispatcher`] and other REPLs,
 /// because Telegram disallow multiple requests at the same time from the same
 /// bot.
 ///
+/// ## Dependency requirements
+///
+///  - Those of [`HandlerExt::add_command`].
+///
 /// [`Dispatcher`]: crate::dispatching::Dispatcher
 /// [`commands_repl`]: crate::dispatching::repls::commands_repl()
 /// [`UpdateListener`]: crate::dispatching::update_listeners::UpdateListener

src/dispatching2/repls/mod.rs

@@ -1,4 +1,5 @@
-//mod commands_repl;
+//! REPLs for dispatching updates.
+
 //mod dialogues_repl;
 mod commands_repl;
 mod repl;