From 0d082e0f688c5f15008c4839bbabd136a67b3eea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=A1=D1=8B=D1=80=D1=86=D0=B5=D0=B2=20=D0=92=D0=B0=D0=B4?=
 =?UTF-8?q?=D0=B8=D0=BC=20=D0=98=D0=B3=D0=BE=D1=80=D0=B5=D0=B2=D0=B8=D1=87?=
 <syrtcevvi@gmail.com>
Date: Wed, 3 Jan 2024 14:28:40 +0300
Subject: [PATCH] Extend documentation about filter_* fns

---
 crates/teloxide/src/lib.rs | 49 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/crates/teloxide/src/lib.rs b/crates/teloxide/src/lib.rs
index 1a1c6797..9b67f5de 100644
--- a/crates/teloxide/src/lib.rs
+++ b/crates/teloxide/src/lib.rs
@@ -30,7 +30,56 @@
 //!     <img src=https://github.com/teloxide/teloxide/raw/master/media/throw-dice.gif width=420px />
 //!   </kbd>
 //! </div>
+//! 
+//! ## Working with Updates and Messages
+//! There're a great number of [update kinds](https://docs.rs/teloxide/latest/teloxide/types/enum.UpdateKind.html) and 
+//! [message kinds](https://docs.rs/teloxide/latest/teloxide/types/enum.MessageKind.html) to work with! Usually it's essential to filter specific ones
+//! and process them in *handler functions*. *Teloxide* provides some `filter methods` for `Update` and `Message` types in [UpdateFilterExt](https://docs.rs/teloxide/latest/teloxide/dispatching/trait.UpdateFilterExt.html) 
+//! and [MessageFilterExt](https://docs.rs/teloxide/latest/teloxide/dispatching/trait.MessageFilterExt.html) traits respectively. In addition to filtering, these
+//! methods will inject the appropriate type into your handler functions. For instance, if you use `Update::filter_message`, the `Message` object will be available as a parameter
+//! at your handler functions. Analogously the use of `Message::filter_text` will inject the `String` object.
+//! 
+//! (Note: `filter_text` actually uses a function that returns Option<&str> value, so every filter_.. fn *always* return an `Owned` version of a  type)
+//! 
+//! Moreover, *filter_map* function can inject some object according to the schema flow. More in the example below!
+//! 
+//! Here is a quick example (filter text message and inject it's text into the handler function):
+//! ```no_run
+//! # #[cfg(feature = "ctrlc_handler")]
+//! use teloxide::prelude::*;
 //!
+//! # #[cfg(feature = "ctrlc_handler")]
+//! # #[tokio::main]
+//! # async fn main() {
+//! let bot = Bot::from_env();
+//! let schema = Update::filter_message()
+//!     // Inject the `User` object representing the author of an incoming 
+//!     // message into every successive handler function
+//!     .filter_map(|update: Update| update.user().cloned())
+//!     .branch(
+//!         // Use filter_text method of MessageFilterExt to accept 
+//!         // only textual messages. Others will be ignored by this handler
+//!         Message::filter_text().endpoint(process_text_message)
+//!     );
+//! 
+//! Dispatcher::builder(bot, schema)
+//!        .build()
+//!        .dispatch()
+//!        .await;
+//!    Ok(())
+//! })
+//! .await;
+//! # } #[cfg(not(feature = "ctrlc_handler"))] fn main(){}
+//! 
+//! /// Replies to the user's text messages
+//! async fn process_text_message(bot: Bot, user: User, message_text: String) -> Result<(), teloxide::RequestError> {
+//!     // The id of a chat with a user is the same as his telegram_id 
+//!     // from the bot's perspective
+//!     bot.send_message(user.id, format!("Hi! You sent: {message_text}"))
+//!     Ok(())
+//! }
+//! ```
+//! 
 //! [Telegram bots]: https://telegram.org/blog/bot-revolution
 //! [`async`/`.await`]: https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html
 //! [Rust]: https://www.rust-lang.org/