From c545be9f5b798a490fcd3f3cb3f506782016d4f1 Mon Sep 17 00:00:00 2001 From: Desiders Date: Sat, 16 Sep 2023 10:59:06 +0300 Subject: [PATCH] Add docs for some filters in `filters` module --- src/filters.rs | 39 ++++++++++++++++++++++++++++++++++++- src/filters/chat_type.rs | 7 +++++++ src/filters/command.rs | 6 +++++- src/filters/content_type.rs | 7 +++++++ 4 files changed, 57 insertions(+), 2 deletions(-) diff --git a/src/filters.rs b/src/filters.rs index 76716337..43126414 100644 --- a/src/filters.rs +++ b/src/filters.rs @@ -1,3 +1,40 @@ +//! Filters are main part of the library used to filter incoming updates and allow call handlers by their data (text, chat, user, command, etc.), +//! [`context`] (state, db, etc.) and other conditions. +//! +//! [`Filter`] is a trait that accepts [`bot`], [`update`] and [`context`] and returns `true` if the filter passes, otherwise `false`. +//! You can use [`Filter`] trait to create your own filters or use one of the ready-made implementations. +//! Most likely you will have to write your filters, so we recommend you to check out the [`examples/uppercase_filter`] to see how to create your own filters +//! and check ready-made implementations. +//! +//! Filters can be combined with logical operators [`And`] and [`Or`] and inverted with [`Invert`]. +//! Each filter has a method [`Filter::invert`], [`Filter::and`] and [`Filter::or`] to create [`Invert`], [`And`] and [`Or`] filters respectively. +//! +//! Ready-made implementations: +//! * [`ChatType`]: +//! Filter for checking the type of chat. +//! Usually used with [`ChatTypeEnum`] (or its string representation) to check the type of chat. +//! Creates with `one` or `many` methods. +//! * [`Command`]: +//! This filter checks if the message is a command. +//! Filter accepts [`PatternType`] that represents a command pattern type for verification, +//! for example, text, [`BotCommand`] (just alias to text of command) or [`Regex`]. +//! You can create a filter with `new` method with transferring all necessary data at once, or use [`CommandBuilder`] to create a filter step by step. +//! Instead of [`CommandBuilder`] you can use [`Command`] `one`, `one_with_prefix`, `many`, `many_with_prefix` methods. +//! * [`ContentType`]: +//! Filter for checking the type of content. +//! Usually used with [`ContentTypeEnum`] (or its string representation) to check the type of content. +//! Creates with `one` or `many` methods. +//! * [`State`]: +//! Filter for checking the state of the user/chat/etc. +//! Filter accepts [`StateType`] that represents a state type for verification, +//! for example, equal, any or none. +//! You can create a filter with `one` or `many` if you want to check the state with the exact value +//! or use `any` or `none` if you want to check the state with any value or without state, respectively. +//! +//! [`context`]: crate::context::Context +//! [`ChatTypeEnum`]: crate::enums::ChatType +//! [`ContentTypeEnum`]: crate::enums::ContentType + pub mod base; pub mod chat_type; pub mod command; @@ -9,7 +46,7 @@ pub mod user; pub use base::Filter; pub use chat_type::ChatType; -pub use command::{Command, CommandObject}; +pub use command::{Command, CommandBuilder, CommandObject}; pub use content_type::ContentType; pub use logical::{And, Invert, Or}; pub use state::{State, StateType}; diff --git a/src/filters/chat_type.rs b/src/filters/chat_type.rs index 1aaf9f5e..c7e81a88 100644 --- a/src/filters/chat_type.rs +++ b/src/filters/chat_type.rs @@ -4,18 +4,25 @@ use crate::{client::Bot, context::Context, enums::ChatType as ChatTypeEnum, type use async_trait::async_trait; +/// Filter for checking the type of chat #[derive(Debug, Clone)] pub struct ChatType { chat_types: Vec, } impl ChatType { + /// Creates a new [`ChatType`] filter with one allowed chat type. + /// # Notes + /// You can use [`ChatTypeEnum`] or its string representation. pub fn one(chat_type: impl Into) -> Self { Self { chat_types: vec![chat_type.into()], } } + /// Creates a new [`ChatType`] filter with many allowed chat types. + /// # Notes + /// You can use [`ChatTypeEnum`] or its string representation. pub fn many(chat_types: I) -> Self where T: Into, diff --git a/src/filters/command.rs b/src/filters/command.rs index 6262d20c..649b05c0 100644 --- a/src/filters/command.rs +++ b/src/filters/command.rs @@ -53,8 +53,12 @@ impl From for PatternType<'_> { } } -/// This filter checks if the message is a command +/// This filter checks if the message is a command. /// +/// Filter accepts [`PatternType`] that represents a command pattern type for verification, +/// for example, text, [`BotCommand`] or [`Regex`]. +/// +/// # Notes /// You can use parsed command using [`CommandObject`] struct in handler arguments, /// or get it from [`Context`] by `command` key. #[derive(Debug, Clone)] diff --git a/src/filters/content_type.rs b/src/filters/content_type.rs index 6bd44695..93966a6e 100644 --- a/src/filters/content_type.rs +++ b/src/filters/content_type.rs @@ -4,12 +4,16 @@ use crate::{client::Bot, context::Context, enums::ContentType as ContentTypeEnum use async_trait::async_trait; +/// Filter for checking the type of content #[derive(Debug, Clone)] pub struct ContentType { content_types: Vec, } impl ContentType { + /// Creates a new [`ContentType`] filter with one allowed content type + /// # Notes + /// You can use [`ContentTypeEnum`] or its string representation #[must_use] pub fn one(content_type: impl Into) -> Self { Self { @@ -17,6 +21,9 @@ impl ContentType { } } + /// Creates a new [`ContentType`] filter with many allowed content types + /// # Notes + /// You can use [`ContentTypeEnum`] or its string representation #[must_use] pub fn many(content_types: I) -> Self where