Simplify examples/dispatching2_features.rs

README.md

@@ -84,6 +84,7 @@ tokio = { version =  "1.8", features = ["rt-multi-thread", "macros"] }
 This bot replies with a dice throw to each received message:
 
 ([Full](examples/dices.rs))
+
 ```rust,no_run
 use teloxide::prelude2::*;
 

examples/dispatching2_features.rs

@@ -1,64 +1,62 @@
-//! This example provide quick overview of the new features in the
+// This example provide a quick overview of the new features in the
-//! `dispatching2` module.
+// `dispatching2` module.
 
 use rand::Rng;
-/// Note that you need to import `prelude2` because `prelude` contains
+
-/// items from the old dispatching system (it may change in future versions).
+// You need to import `prelude2` because `prelude` contains items from the old
-use teloxide::prelude2::*;
+// dispatching system, which will be deprecated in the future.
-use teloxide::{types::Update, utils::command::BotCommand};
+use teloxide::{
+    prelude2::*,
+    types::{Dice, Update},
+    utils::command::BotCommand,
+};
 
 #[tokio::main]
 async fn main() {
-    // Start you main as early: start logging, create bot, etc.
     teloxide::enable_logging!();
     log::info!("Starting dispatching2_features_bot...");
+
     let bot = Bot::from_env().auto_send();
 
     let parameters = ConfigParameters {
-        bot_maintainer: 268486177, // Paste your ID if you run this bot.
+        bot_maintainer: 268486177, // Paste your ID to run this bot.
         maintainer_username: None,
     };
 
     let handler = Update::filter_message()
-        // Branch is a special method that allow you to handle update several ways.
+        // You can use branching to define multiple ways in which an update will be handled. If the
+        // first branch fails, an update will be passed to the second branch, and so on.
         .branch(
-            // Filter allow you to filter updates by some condition.
+            // Filtering allow you to filter updates by some condition.
-            dptree::filter(
+            dptree::filter(|msg: Message| msg.chat.is_group() || msg.chat.is_supergroup())
-                |msg: Message| msg.chat.is_group() || msg.chat.is_supergroup(),
+                // An endpoint is the last update handler.
-            )
+                .endpoint(|msg: Message, bot: AutoSend<Bot>| async move {
-            // Endpoint is a last message handler.
+                    log::info!("Received a message from a group chat.");
-            .endpoint(|msg: Message, bot: AutoSend<Bot>| async move {
+                    bot.send_message(msg.chat.id, "This is a group chat.").await?;
-                log::info!("Received message from the group chat.");
+                    respond(())
-                bot.send_message(msg.chat.id, "This is a group chat.").await?;
+                }),
-                respond(())
-            }),
-        )
-        // Note that we cannot filter messages from public chats in the next branch,
-        // because they all is handled by previous branch.
-        .branch(
-            // There are some `filter` functions on message, that filters events. This
-            // filter will filter only messages with dices.
-            Message::filter_dice().endpoint(|msg: Message, bot: AutoSend<Bot>| async move {
-                bot.send_message(msg.chat.id, "This is a dice!")
-                    .reply_to_message_id(msg.id)
-                    .await?;
-                Ok(())
-            }),
         )
         .branch(
-            // If you do not like photos, you can break their handling like that.
+            // There are some extension filtering functions on `Message`. The following filter will
-            Message::filter_photo().endpoint(|| async move { Ok(()) }),
+            // filter only messages with dices.
+            Message::filter_dice().endpoint(
+                |msg: Message, dice: Dice, bot: AutoSend<Bot>| async move {
+                    bot.send_message(msg.chat.id, format!("Dice value: {}", dice.value))
+                        .reply_to_message_id(msg.id)
+                        .await?;
+                    Ok(())
+                },
+            ),
         )
         .branch(
             dptree::entry()
-                // This method allows to parse text messages commands.
+                // Filter commands: the next handlers will receive a parsed `SimpleCommand`.
                 .filter_command::<SimpleCommand>()
-                // Next we can add `SimpleCommand` in the argument of endpoint. If
+                // If a command parsing fails, this handler will not be executed.
-                // command parsing fails, this endpoint will not be called.
                 .endpoint(simple_commands_handler),
         )
         .branch(
-            // Filter maintainer by used ID.
+            // Filter a maintainer by a used ID.
             dptree::filter(|msg: Message, cfg: ConfigParameters| {
                 msg.from().map(|user| user.id == cfg.bot_maintainer).unwrap_or_default()
             })
@@ -71,7 +69,6 @@ async fn main() {
                             let value: u64 = rng.gen_range(from..=to);
 
                             bot.send_message(msg.chat.id, value.to_string()).await?;
-
                             Ok(())
                         }
                     }
@@ -79,23 +76,18 @@ async fn main() {
             ),
         );
 
-    // Start create dispatcher.
     Dispatcher::builder(bot, handler)
-        // You can specify dependencies to that you have access inside of handlers. It may be
+        // Here you specify initial dependencies that all handlers will receive; they can be
-        // configs, connection to Database, or dialogue storage (see more in the dialogue_bot
+        // database connections, configurations, and other auxiliary arguments. It is similar to
-        // example). It is similar to the `actix_web::Extensions`.
+        // `actix_web::Extensions`.
         .dependencies(dptree::deps![parameters])
-        // Now handlers don't use streams. Instead handler is special constructs from `dptree`
+        // If no handler succeeded to handle an update, this closure will be called.
-        // library. Any `*_handler` accepts function `Fn(UpdateHandler) -> UpdateHandler`
-        // which is builder for the handlers. Note that you _must_ use it instead of using
-        // `dptree` methods forward.
         .default_handler(|upd| async move {
-            // This handler handles updates that do not handled by other handlers.
             log::warn!("Unhandled update: {:?}", upd);
         })
-        // If `Result::Err` returns from the dispatcher, it goes here.
+        // If the dispatcher fails for some reason, execute this handler.
         .error_handler(LoggingErrorHandler::with_custom_text(
-            "Error has occurred in the dispatcher",
+            "An error has occurred in the dispatcher",
         ))
         .build()
         .setup_ctrlc_handler()
@@ -109,7 +101,6 @@ struct ConfigParameters {
     maintainer_username: Option<String>,
 }
 
-// We do not change BotCommand api.
 #[derive(BotCommand, Clone)]
 #[command(rename = "lowercase", description = "Simple commands")]
 enum SimpleCommand {
@@ -155,6 +146,7 @@ async fn simple_commands_handler(
             format!("{}", msg.from().unwrap().id)
         }
     };
+
     bot.send_message(msg.chat.id, text).await?;
 
     Ok(())