Lay out the difference between REPLs and dispatching

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;

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,
@@ -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<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

@@ -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,