Merge pull request #690 from teloxide/repls-dispatching-doc

Explain the difference between REPLs and dispatching

src/dispatching.rs

@@ -192,12 +192,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 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:
+//!  - Handle different kinds of [`Update`];
+//!  - [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
 //! [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;

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<R, Err, Key> {
     bot: R,
     dependencies: DependencyMap,
@@ -171,11 +174,14 @@ 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`].
 ///
+/// See also: ["Dispatching or
+/// REPLs?"](../dispatching/index.html#dispatching-or-repls)
+///
 /// [`distribution_function`]: DispatcherBuilder::distribution_function
 pub struct Dispatcher<R, Err, Key> {
     bot: R,

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,

src/dispatching/repls/repl.rs

@@ -15,6 +15,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,
@@ -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,