From 3038892e3262f10c42a7bef434b981245cd802c8 Mon Sep 17 00:00:00 2001 From: Hirrolot Date: Sun, 24 Jul 2022 18:56:53 +0600 Subject: [PATCH 1/6] Lay out the difference between REPLs and dispatching Former-commit-id: 3bdd6bdcb79f4dcd7967c805466ff3561d0b9233 --- src/dispatching.rs | 24 ++++++++++++++++++++++++ src/dispatching/dispatcher.rs | 6 ++++++ src/dispatching/repls/commands_repl.rs | 6 ++++++ src/dispatching/repls/repl.rs | 6 ++++++ 4 files changed, 42 insertions(+) diff --git a/src/dispatching.rs b/src/dispatching.rs index e0440705..fb482e34 100644 --- a/src/dispatching.rs +++ b/src/dispatching.rs @@ -187,12 +187,36 @@ //! useful features. See [`examples/dispatching_features.rs`] as a more involved //! example. //! +//! ## Dispatching or REPLs? +//! +//! The difference between dispatching and the REPLs ([`crate::repl`] & co) is +//! that dispatching allows you a greater degree of flexibility at the cost of a +//! bit more complicated setup. +//! +//! Here are things that dispatching can do, but REPLs can't: +//! - Handle different kinds of [`Update`]; +//! - [Pass dependencies](struct.DispatcherBuilder.html#method.dependencies) to +//! handlers; +//! - Disable a [default Ctrl-C +//! handling](struct.DispatcherBuilder.html#method.enable_ctrlc_handler); +//! - Control your +//! [default](struct.DispatcherBuilder.html#method.default_handler) and +//! [error](struct.DispatcherBuilder.html#method.error_handler) handlers; +//! - Use [dialogues](dialogue/index.html). +//! - Use [`dptree`]-related functionality. +//! - Probably more. +//! +//! Thus, REPLs are good for simple bots and rapid prototyping, but for more +//! involved scenarios, we recommend using [`DispatcherBuilder`]/[`Dispatcher`] +//! together with [`dptree`]. +//! //! [`examples/purchase.rs`]: https://github.com/teloxide/teloxide/blob/master/examples/purchase.rs //! [`Update::filter_message`]: crate::types::Update::filter_message //! [`Update::filter_callback_query`]: crate::types::Update::filter_callback_query //! [chain of responsibility]: https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern //! [dependency injection (DI)]: https://en.wikipedia.org/wiki/Dependency_injection //! [`examples/dispatching_features.rs`]: https://github.com/teloxide/teloxide/blob/master/examples/dispatching_features.rs +//! [`Update`]: crate::types::Update #[cfg(all(feature = "ctrlc_handler"))] pub mod repls; diff --git a/src/dispatching/dispatcher.rs b/src/dispatching/dispatcher.rs index 6ff568e6..27a82f47 100644 --- a/src/dispatching/dispatcher.rs +++ b/src/dispatching/dispatcher.rs @@ -27,6 +27,9 @@ use std::{ }; /// The builder for [`Dispatcher`]. +/// +/// See also: ["Dispatching or +/// REPLs?"](../dispatching/index.html#dispatching-or-repls) pub struct DispatcherBuilder { bot: R, dependencies: DependencyMap, @@ -176,6 +179,9 @@ where /// determine a chat ID of an incoming update, it will be handled concurrently. /// Note that this behaviour can be altered with [`distribution_function`]. /// +/// See also: ["Dispatching or +/// REPLs?"](../dispatching/index.html#dispatching-or-repls) +/// /// [`distribution_function`]: DispatcherBuilder::distribution_function pub struct Dispatcher { bot: R, diff --git a/src/dispatching/repls/commands_repl.rs b/src/dispatching/repls/commands_repl.rs index 6967dfa0..9f8f9b93 100644 --- a/src/dispatching/repls/commands_repl.rs +++ b/src/dispatching/repls/commands_repl.rs @@ -18,6 +18,9 @@ use teloxide_core::requests::Requester; /// supply dependencies or describe more complex dispatch logic, please use /// [`Dispatcher`]. /// +/// See also: ["Dispatching or +/// REPLs?"](dispatching/index.html#dispatching-or-repls) +/// /// ## Caution /// /// **DO NOT** use this function together with [`Dispatcher`] and other REPLs, @@ -58,6 +61,9 @@ where /// supply dependencies or describe more complex dispatch logic, please use /// [`Dispatcher`]. /// +/// See also: ["Dispatching or +/// REPLs?"](dispatching/index.html#dispatching-or-repls) +/// /// ## Caution /// /// **DO NOT** use this function together with [`Dispatcher`] and other REPLs, diff --git a/src/dispatching/repls/repl.rs b/src/dispatching/repls/repl.rs index 38a8093d..329c1e51 100644 --- a/src/dispatching/repls/repl.rs +++ b/src/dispatching/repls/repl.rs @@ -14,6 +14,9 @@ use teloxide_core::requests::Requester; /// REPLs are meant only for simple bots and rapid prototyping. If you need to /// supply dependencies or describe more complex dispatch logic, please use /// [`Dispatcher`]. +/// +/// See also: ["Dispatching or +/// REPLs?"](dispatching/index.html#dispatching-or-repls) /// /// ## Caution /// @@ -44,6 +47,9 @@ where /// supply dependencies or describe more complex dispatch logic, please use /// [`Dispatcher`]. /// +/// See also: ["Dispatching or +/// REPLs?"](dispatching/index.html#dispatching-or-repls) +/// /// # Caution /// /// **DO NOT** use this function together with [`Dispatcher`] and other REPLs, From 7c1af1265bbb8a69189db8b7e9d556e6a46ba3ea Mon Sep 17 00:00:00 2001 From: Hirrolot Date: Sun, 24 Jul 2022 18:57:33 +0600 Subject: [PATCH 2/6] A doc fix for `Dispatcher` Former-commit-id: 7b18d62296b8fb8e7e656a7de41f1003de16d816 --- src/dispatching/dispatcher.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/dispatching/dispatcher.rs b/src/dispatching/dispatcher.rs index 27a82f47..9e009401 100644 --- a/src/dispatching/dispatcher.rs +++ b/src/dispatching/dispatcher.rs @@ -174,7 +174,7 @@ where /// The base for update dispatching. /// -/// Updates from different chats are handles concurrently, whereas updates from +/// Updates from different chats are handled concurrently, whereas updates from /// the same chats are handled sequentially. If the dispatcher is unable to /// determine a chat ID of an incoming update, it will be handled concurrently. /// Note that this behaviour can be altered with [`distribution_function`]. From 839d4705ae540816c9a67cafe21583f0c08f181e Mon Sep 17 00:00:00 2001 From: Hirrolot Date: Sun, 24 Jul 2022 19:01:36 +0600 Subject: [PATCH 3/6] Fix formatting Former-commit-id: a59fb0ddea9e2a32fb5598973f2622e5a21c2a12 --- src/dispatching/repls/repl.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/dispatching/repls/repl.rs b/src/dispatching/repls/repl.rs index 329c1e51..8ae7cbba 100644 --- a/src/dispatching/repls/repl.rs +++ b/src/dispatching/repls/repl.rs @@ -14,7 +14,7 @@ use teloxide_core::requests::Requester; /// REPLs are meant only for simple bots and rapid prototyping. If you need to /// supply dependencies or describe more complex dispatch logic, please use /// [`Dispatcher`]. -/// +/// /// See also: ["Dispatching or /// REPLs?"](dispatching/index.html#dispatching-or-repls) /// From 40e311d3a000fc59bef3fc3417d6378a4a8626ff Mon Sep 17 00:00:00 2001 From: Hirrolot Date: Sun, 24 Jul 2022 19:32:09 +0600 Subject: [PATCH 4/6] Apply a tiny doc review suggestion Co-authored-by: Waffle Maybe Former-commit-id: ab0292649fb73cbba8bbbb5aa8eb911b981e5e7a --- src/dispatching.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/dispatching.rs b/src/dispatching.rs index fb482e34..bb2a7e7b 100644 --- a/src/dispatching.rs +++ b/src/dispatching.rs @@ -190,7 +190,7 @@ //! ## Dispatching or REPLs? //! //! The difference between dispatching and the REPLs ([`crate::repl`] & co) is -//! that dispatching allows you a greater degree of flexibility at the cost of a +//! that dispatching gives you a greater degree of flexibility at the cost of a //! bit more complicated setup. //! //! Here are things that dispatching can do, but REPLs can't: From a654491d6ffe58f61ced3daa2c4a6db0da5f6407 Mon Sep 17 00:00:00 2001 From: Hirrolot Date: Sun, 24 Jul 2022 19:40:35 +0600 Subject: [PATCH 5/6] Simplify the doc sentence (code review) Former-commit-id: 0f526ebe99b75a6aeff3f577256dd8a572bb2bd5 --- src/dispatching.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/dispatching.rs b/src/dispatching.rs index fb482e34..4d4a985a 100644 --- a/src/dispatching.rs +++ b/src/dispatching.rs @@ -207,8 +207,7 @@ //! - Probably more. //! //! Thus, REPLs are good for simple bots and rapid prototyping, but for more -//! involved scenarios, we recommend using [`DispatcherBuilder`]/[`Dispatcher`] -//! together with [`dptree`]. +//! involved scenarios, we recommend using dispatching over REPLs. //! //! [`examples/purchase.rs`]: https://github.com/teloxide/teloxide/blob/master/examples/purchase.rs //! [`Update::filter_message`]: crate::types::Update::filter_message From ef46649b23c8a92b45f6859017701f37b10dddd2 Mon Sep 17 00:00:00 2001 From: Maybe Waffle Date: Sun, 24 Jul 2022 19:11:57 +0400 Subject: [PATCH 6/6] Improve link formatting Former-commit-id: 1942b8f49b7987e205cc8444b0a4d890eacc049e --- src/dispatching.rs | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/dispatching.rs b/src/dispatching.rs index 25a60e52..0fc1ceda 100644 --- a/src/dispatching.rs +++ b/src/dispatching.rs @@ -195,20 +195,21 @@ //! //! Here are things that dispatching can do, but REPLs can't: //! - Handle different kinds of [`Update`]; -//! - [Pass dependencies](struct.DispatcherBuilder.html#method.dependencies) to -//! handlers; -//! - Disable a [default Ctrl-C -//! handling](struct.DispatcherBuilder.html#method.enable_ctrlc_handler); -//! - Control your -//! [default](struct.DispatcherBuilder.html#method.default_handler) and -//! [error](struct.DispatcherBuilder.html#method.error_handler) handlers; -//! - Use [dialogues](dialogue/index.html). +//! - [Pass dependencies] to handlers; +//! - Disable a [default Ctrl-C handling]; +//! - Control your [default] and [error] handlers; +//! - Use [dialogues]. //! - Use [`dptree`]-related functionality. //! - Probably more. //! //! Thus, REPLs are good for simple bots and rapid prototyping, but for more //! involved scenarios, we recommend using dispatching over REPLs. //! +//! [Pass dependencies]: DispatcherBuilder#method.dependencies +//! [default Ctrl-C handling]: DispatcherBuilder#method.enable_ctrlc_handler +//! [default]: DispatcherBuilder#method.default_handler +//! [error]: DispatcherBuilder#method.error_handler +//! [dialogues]: dialogue //! [`examples/purchase.rs`]: https://github.com/teloxide/teloxide/blob/master/examples/purchase.rs //! [`Update::filter_message`]: crate::types::Update::filter_message //! [`Update::filter_callback_query`]: crate::types::Update::filter_callback_query