Eventually fix the docs

src/dispatching/dialogue/mod.rs

@@ -23,15 +23,16 @@
 //! from the storage, otherwise ([`DialogueStage::Next`]) force the storage to
 //! update the session.
 //!
-//! Please, see https://github.com/teloxide/teloxide/tree/dev/examples/simple_dialogue.
+//! Please, see [examples/simple_dialogue] as an example.
 //!
-//! [`Storage`]: crate::dispatching::session::Storage
-//! [`DialogueDispatcher`]: crate::dispatching::session::SessionDispatcher
+//! [`Storage`]: crate::dispatching::dialogue::Storage
+//! [`DialogueDispatcher`]: crate::dispatching::dialogue::DialogueDispatcher
 //! [`DialogueStage::Exit`]:
 //! crate::dispatching::dialogue::DialogueStage::Exit
 //! [`DialogueStage::Next`]: crate::dispatching::dialogue::DialogueStage::Next
 //! [`CtxHandler`]: crate::dispatching::CtxHandler
 //! [`Dispatcher`]: crate::dispatching::Dispatcher
+//! [examples/simple_dialogue]: https://github.com/teloxide/teloxide/tree/dev/examples/simple_dialogue
 
 #![allow(clippy::module_inception)]
 #![allow(clippy::type_complexity)]

src/dispatching/mod.rs

@@ -1,19 +1,26 @@
 //! Updates dispatching.
 //!
-//! The key type here is [`Dispatcher`]. It encapsulates middlewares, handlers
-//! for [10 update kinds], and [`ErrorHandler`] for them. When [`Update`] is
-//! received from Telegram, the following steps are executed:
+//! The key type here is [`Dispatcher`]. It encapsulates [`Bot`], handlers for
+//! [11 update kinds] (+ for [`Update`]) and [`ErrorHandler`] for them. When
+//! [`Update`] is received from Telegram, the following steps are executed:
 //!
-//!  1. It is supplied into all registered middlewares.
-//!  2. It is supplied to an appropriate handler.
-//!  3. If a handler has returned an error, the error is supplied into an error
-//! handler.
+//!  1. It is supplied into an appropriate handler (the first ones is those who
+//! accept [`Update`]).
+//!  2. If a handler failed, invoke [`ErrorHandler`] with the corresponding
+//! error.
+//!  3. If a handler has returned [`DispatcherHandlerResult`] with `None`,
+//! terminate the pipeline, otherwise supply an update into the next handler
+//! (back to step 1).
 //!
-//! That's simple!
+//! The pipeline is executed until either all the registered handlers were
+//! executed, or one of handlers has terminated the pipeline. That's simple!
 //!
-//! Note that handlers implement [`CtxHandler`], which means that you are able
-//! to supply [`SessionDispatcher`] as a handler, since it implements
+//!  1. Note that handlers implement [`CtxHandler`], which means that you are
+//! able to supply [`DialogueDispatcher`] as a handler, since it implements
 //! [`CtxHandler`] too!
+//!  2. Note that you don't always need to return [`DispatcherHandlerResult`]
+//! explicitly, because of automatic conversions. Just return `Result<(), E>` if
+//! you want to terminate the pipeline (see the example below).
 //!
 //! ## Examples
 //! The ping-pong bot ([full](https://github.com/teloxide/teloxide/blob/dev/examples/ping_pong_bot/)):
@@ -35,12 +42,17 @@
 //! # }
 //! ```
 //!
+//! For a bit more complicated example, please see [examples/simple_dialogue].
+//!
 //! [`Dispatcher`]: crate::dispatching::Dispatcher
-//! [10 update kinds]: crate::types::UpdateKind
+//! [11 update kinds]: crate::types::UpdateKind
 //! [`Update`]: crate::types::Update
 //! [`ErrorHandler`]: crate::dispatching::ErrorHandler
 //! [`CtxHandler`]: crate::dispatching::CtxHandler
-//! [`SessionDispatcher`]: crate::dispatching::SessionDispatcher
+//! [`DialogueDispatcher`]: crate::dispatching::dialogue::DialogueDispatcher
+//! [`DispatcherHandlerResult`]: crate::dispatching::DispatcherHandlerResult
+//! [`Bot`]: crate::Bot
+//! [examples/simple_dialogue]: https://github.com/teloxide/teloxide/tree/dev/examples/simple_dialogue
 
 mod ctx_handlers;
 pub mod dialogue;

src/errors.rs

@@ -348,9 +348,9 @@ pub enum ApiErrorKind {
     /// chat.
     ///
     /// May happen in methods:
-    /// 1. [`PinMessage`]
+    /// 1. [`PinChatMessage`]
     ///
-    /// [`PinMessage`]: crate::requests::PinMessage
+    /// [`PinChatMessage`]: crate::requests::PinChatMessage
     #[serde(rename = "Bad Request: not enough rights to pin a message")]
     NotEnoughRightsToPinMessage,