Improve documentation and fix typos

crates/teloxide/src/dispatching/filter_ext.rs

@@ -88,7 +88,6 @@ define_message_ext! {
     (filter_migration, Message::chat_migration),
     (filter_migration_from, Message::migrate_from_chat_id),
     (filter_migration_to, Message::migrate_to_chat_id),
-
     (filter_reply_to_message, Message::reply_to_message),
     (filter_forward_from, Message::forward_from),
     // Rest variants of a MessageKind

crates/teloxide/src/lib.rs

@@ -31,58 +31,78 @@
 //!   </kbd>
 //! </div>
 //!
+//! [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/
+
 //! ## 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)
+//! There is a great number of [update kinds] and [message kinds] 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] and [MessageFilterExt] 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 instance of the [Message] will be available as
+//! a parameter for your handler functions. Similarly the use of
+//! [Message::filter_text] will inject a [String] into the context.
 //!
-//! Moreover, *filter_map* function can inject some object according to the schema flow. More in the example below!
+//! Moreover, [filter_map] function can inject some dependencies 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):
+//! 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::*, types::User};
-//! use teloxide::prelude::*;
 //!
-//! # #[cfg(feature = "ctrlc_handler")]
+//! pub type Error = Box<dyn std::error::Error + Send + Sync>;
-//! # #[tokio::main]
+//!
-//! # async fn main() {
+//! #[tokio::main]
+//! async fn main() -> Result<(), Error> {
 //!     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
+//!            Inject the `User` object representing the author of an incoming
-//!     .filter_map(|update: Update| update.user().cloned())
+//!            message into every successive handler function (1)
+//!         */
+//!         .filter_map(|update: Update| update.from().cloned())
 //!         .branch(
-//!         // Use filter_text method of MessageFilterExt to accept 
+//!             /*
-//!         // only textual messages. Others will be ignored by this handler
+//!                Use filter_text method of MessageFilterExt to accept
-//!         Message::filter_text().endpoint(process_text_message)
+//!                only textual messages. Others will be ignored by this handler (2)
+//!             */
+//!             Message::filter_text().endpoint(process_text_message),
 //!         );
 //!
-//! Dispatcher::builder(bot, schema)
+//!     Dispatcher::builder(bot, schema).build().dispatch().await;
-//!        .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> {
+//! async fn process_text_message(bot: Bot, user: User, message_text: String) -> Result<(), Error> {
-//!     // The id of a chat with a user is the same as his telegram_id 
+//!     /*
-//!     // from the bot's perspective
+//!        The id of a chat with a user is the same as his telegram_id
-//!     bot.send_message(user.id, format!("Hi! You sent: {message_text}"))
+//!        from the bot's perspective.
+//!
+//!        Injected dependencies:
+//!        - Bot is provided by the Dispatcher::dispatch
+//!        - User is provided by the (1)
+//!        - String is provided by the (2)
+//!     */
+//!     bot.send_message(user.id, format!("Hi! You sent: {message_text}"));
 //!     Ok(())
 //! }
 //! ```
 //!
-//! [Telegram bots]: https://telegram.org/blog/bot-revolution
+//! [update kinds]: crate::types::UpdateKind
-//! [`async`/`.await`]: https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html
+//! [message kinds]: crate::types::MessageKind
-//! [Rust]: https://www.rust-lang.org/
+//! [Update]: crate::types::Update
+//! [Message]: crate::types::Message
+//! [Message::filter_text]: crate::dispatching::MessageFilterExt::filter_text
+//! [UpdateFilterExt]: crate::dispatching::MessageFilterExt
+//! [MessageFilterExt]: crate::dispatching::UpdateFilterExt
+//! [Update::filter_message]: crate::dispatching::UpdateFilterExt::filter_message
+//! [filter_map]: crate::prelude::Handler::filter_map
 
 // This hack is used to cancel formatting for a Markdown table. See [1], [2], and [3].
 //