From e92eef4a7cb1d8cca8b7a5df47dc03663b229865 Mon Sep 17 00:00:00 2001 From: Hirrolot Date: Mon, 31 Jan 2022 19:23:47 +0600 Subject: [PATCH] Document some stuff --- src/dispatching2/filter_ext.rs | 111 ++++++++++++++---------- src/dispatching2/handler_ext.rs | 14 ++- src/dispatching2/repls/commands_repl.rs | 12 ++- src/dispatching2/repls/mod.rs | 3 +- 4 files changed, 87 insertions(+), 53 deletions(-) diff --git a/src/dispatching2/filter_ext.rs b/src/dispatching2/filter_ext.rs index eff56ecc..261bfad6 100644 --- a/src/dispatching2/filter_ext.rs +++ b/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 { - $( define_ext!(@sig $func, $arg_ty); )* + $( define_ext!(@sig $func, $fn_doc); )* } impl $ext_name 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 { - ($fn_name:expr) => { - |x| $fn_name(&x).map(ToOwned::to_owned) - }; +macro_rules! define_message_ext { + ($( ($func:ident, $fn_name:path) ,)*) => { + 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! { - MessageFilterExt, Message => - (filter_from, types::User, to_owned_fn![Message::from]), - (filter_animation, types::Animation, to_owned_fn![Message::animation]), - (filter_audio, types::Audio, to_owned_fn![Message::audio]), - (filter_contact, types::Contact, to_owned_fn![Message::contact]), - (filter_document, types::Document, to_owned_fn![Message::document]), - (filter_location, types::Location, to_owned_fn![Message::location]), - (filter_photo, [types::PhotoSize], to_owned_fn![Message::photo]), - (filter_poll, types::Poll, to_owned_fn![Message::poll]), - (filter_sticker, types::Sticker, to_owned_fn![Message::sticker]), - (filter_text, str, to_owned_fn![Message::text]), - (filter_reply_to_message, Message, to_owned_fn![Message::reply_to_message]), - (filter_forward_from, types::ForwardedFrom, to_owned_fn![Message::forward_from]), - (filter_new_chat_members, [types::User], to_owned_fn![Message::new_chat_members]), - (filter_left_chat_member, types::User, to_owned_fn![Message::left_chat_member]), - (filter_pinned, Message, to_owned_fn![Message::pinned_message]), - (filter_dice, types::Dice, to_owned_fn![Message::dice]), +define_message_ext! { + (filter_from, Message::from), + (filter_animation, Message::animation), + (filter_audio, Message::audio), + (filter_contact, Message::contact), + (filter_document, Message::document), + (filter_location, Message::location), + (filter_photo, Message::photo), + (filter_poll, Message::poll), + (filter_sticker, Message::sticker), + (filter_text, Message::text), + (filter_reply_to_message, Message::reply_to_message), + (filter_forward_from, Message::forward_from), + (filter_new_chat_members, Message::new_chat_members), + (filter_left_chat_member, Message::left_chat_member), + (filter_pinned, Message::pinned_message), + (filter_dice, Message::dice), } -macro_rules! kind { - ($kind:ident) => { - |update: Update| match update.kind { - UpdateKind::$kind(x) => Some(x), - _ => None, +macro_rules! define_update_ext { + ($( ($func:ident, $kind:path) ,)*) => { + define_ext! { + UpdateFilterExt, crate::types::Update => + $(( + $func, + |update: Update| match update.kind { + $kind(x) => Some(x), + _ => None, + }, + concat!("Filters out [`crate::types::", stringify!($kind), "`] objects.") + ),)* } - }; + } } -define_ext! { - UpdateFilterExt, Update => - (filter_message, types::Message, kind![Message]), - (filter_edited_message, types::EditedMessage, kind![EditedMessage]), - (filter_channel_post, types::ChannelPost, kind![ChannelPost]), - (filter_edited_channel_post, types::EditedChannelPost, kind![EditedChannelPost]), - (filter_inline_query, types::InlineQuery, kind![InlineQuery]), - (filter_chosen_inline_result, types::ChosenInlineResult, kind![ChosenInlineResult]), - (filter_callback_query, types::CallbackQuery, kind![CallbackQuery]), - (filter_shipping_query, types::ShippingQuery, kind![ShippingQuery]), - (filter_pre_checkout_query, types::PreCheckoutQuery, kind![PreCheckoutQuery]), - (filter_poll, types::Poll, kind![Poll]), - (filter_poll_answer, types::PollAnswer, kind![PollAnswer]), - (filter_my_chat_member, types::MyChatMember, kind![MyChatMember]), - (filter_chat_member, types::ChatMember, kind![ChatMember]), +// May be expanded in the future. +define_update_ext! { + (filter_message, UpdateKind::Message), + (filter_edited_message, UpdateKind::EditedMessage), + (filter_channel_post, UpdateKind::ChannelPost), + (filter_edited_channel_post, UpdateKind::EditedChannelPost), + (filter_inline_query, UpdateKind::InlineQuery), + (filter_chosen_inline_result, UpdateKind::ChosenInlineResult), + (filter_callback_query, UpdateKind::CallbackQuery), + (filter_shipping_query, UpdateKind::ShippingQuery), + (filter_pre_checkout_query, UpdateKind::PreCheckoutQuery), + (filter_poll, UpdateKind::Poll), + (filter_poll_answer, UpdateKind::PollAnswer), + (filter_my_chat_member, UpdateKind::MyChatMember), + (filter_chat_member, UpdateKind::ChatMember), } diff --git a/src/dispatching2/handler_ext.rs b/src/dispatching2/handler_ext.rs index 955e87ee..fa3c07d0 100644 --- a/src/dispatching2/handler_ext.rs +++ b/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 { + /// Returns a handler that accepts a parsed command `C`. + /// + /// ## Dependency requirements + /// + /// - [`crate::types::Message`] + /// - [`crate::types::Me`] #[must_use] fn add_command(self) -> Self where diff --git a/src/dispatching2/repls/commands_repl.rs b/src/dispatching2/repls/commands_repl.rs index 5997fe7f..77b7462e 100644 --- a/src/dispatching2/repls/commands_repl.rs +++ b/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 diff --git a/src/dispatching2/repls/mod.rs b/src/dispatching2/repls/mod.rs index 2fddc1ce..ca41a0d2 100644 --- a/src/dispatching2/repls/mod.rs +++ b/src/dispatching2/repls/mod.rs @@ -1,4 +1,5 @@ -//mod commands_repl; +//! REPLs for dispatching updates. + //mod dialogues_repl; mod commands_repl; mod repl;