Extend documentation about filter_* fns

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/