Fixing the docs...

src/bot/mod.rs

@@ -8,9 +8,11 @@ use std::{sync::Arc, time::Duration};
 mod api;
 mod download;
 
-/// A Telegram bot used to send requests.
+/// A requests sender.
 ///
-/// No need to put `Bot` into `Arc`, because it's already in.
+/// No need to put it into [`Arc`], because it's already in.
+///
+/// [`Arc`]: std::sync::Arc
 #[derive(Debug, Clone)]
 pub struct Bot {
     token: Arc<str>,

src/dispatching/dialogue/bot_dialogue.rs

@@ -1,5 +1,8 @@
 use crate::{
-    dispatching::{dialogue::TransitionOut, UpdateWithCx},
+    dispatching::{
+        dialogue::{TransitionIn, TransitionOut},
+        UpdateWithCx,
+    },
     types::Message,
 };
 use futures::future::BoxFuture;
@@ -9,6 +12,6 @@ pub trait BotDialogue: Default {
     /// Turns itself into another state, depending on the input message.
     fn dispatch(
         self,
-        cx: UpdateWithCx<Message>,
+        cx: TransitionIn,
     ) -> BoxFuture<'static, TransitionOut<Self>>;
 }

src/dispatching/dialogue/mod.rs

@@ -116,5 +116,5 @@ macro_rules! up {
 /// An input passed into a FSM transition function.
 pub type TransitionIn = UpdateWithCx<Message>;
 
-// A type returned from a FSM transition function.
+/// A type returned from a FSM transition function.
 pub type TransitionOut<D> = ResponseResult<DialogueStage<D>>;

src/dispatching/mod.rs

@@ -1,12 +1,11 @@
 //! Updates dispatching.
 //!
 //! The key type here is [`Dispatcher`]. It encapsulates [`Bot`] and handlers
-//! for [the 11 update kinds].
+//! for [all the update kinds].
 //!
-//! You can register a maximum of 11 handlers for [the 11 update kinds]. Every
-//! handler accept [`tokio::sync::mpsc::UnboundedReceiver`] (the RX halve of an
-//! asynchronous unbounded MPSC channel). Inside a body of your handler, you
-//! typically asynchronously concurrently iterate through updates like this:
+//! Every handler accept [`tokio::sync::mpsc::UnboundedReceiver`] (the RX halve
+//! of an asynchronous channel). Inside a body of your handler, you typically
+//! asynchronously concurrently iterate through updates like this:
 //!
 //! ```
 //! use teloxide::prelude::*;
@@ -29,12 +28,11 @@
 //!    [`tokio::sync::mpsc::UnboundedReceiver`] and return `Future<Output = ()`
 //!    as a handler.
 //!
-//! Since they implement [`DispatcherHandler`] too!
+//! Since they implement [`DispatcherHandler`] too.
 //!
-//! # Examples
-//! ### The ping-pong bot
-//! This bot has a single message handler, which answers "pong" to each incoming
-//! message:
+//! # The ping-pong bot
+//! This bot has a single handler of messages, which answers "pong" to each
+//! incoming message:
 //!
 //! ([Full](https://github.com/teloxide/teloxide/blob/master/examples/ping_pong_bot/src/main.rs))
 //! ```no_run
@@ -67,7 +65,7 @@
 //! [See more examples](https://github.com/teloxide/teloxide/tree/master/examples).
 //!
 //! [`Dispatcher`]: crate::dispatching::Dispatcher
-//! [the 11 update kinds]: crate::types::UpdateKind
+//! [all the update kinds]: crate::types::UpdateKind
 //! [`Update`]: crate::types::Update
 //! [`ErrorHandler`]: crate::dispatching::ErrorHandler
 //! [`DispatcherHandler`]: crate::dispatching::DispatcherHandler

src/dispatching/update_listeners.rs

@@ -92,7 +92,7 @@
 //!   updates `0..=N`.
 //!
 //! # Webhooks
-//! See the [README FAQ about webhooks](https://github.com/teloxide/teloxide/blob/master/README.md#can-i-use-webhooks).
+//! See the [README FAQ about webhooks](https://github.com/teloxide/teloxide/blob/master/README.md#faq).
 //!
 //! [`UpdateListener`]: UpdateListener
 //! [`polling_default`]: polling_default

src/dispatching/update_with_cx.rs

@@ -32,6 +32,7 @@ where
 }
 
 impl UpdateWithCx<Message> {
+    /// A shortcut for `.answer(text).send().await`.
     pub async fn answer_str<T>(&self, text: T) -> ResponseResult<Message>
     where
         T: Into<String>,

src/requests/all/answer_pre_checkout_query.rs

@@ -10,8 +10,11 @@ use crate::{
 /// Once the user has confirmed their payment and shipping details, the Bot API
 /// sends the final confirmation in the form of an [`Update`] with the field
 /// `pre_checkout_query`. Use this method to respond to such pre-checkout
-/// queries. Note: The Bot API must receive an answer within 10 seconds after
-/// the pre-checkout query was sent.
+/// queries.
+///
+/// # Note
+/// The Bot API must receive an answer within 10 seconds after the pre-checkout
+/// query was sent.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#answerprecheckoutquery).
 ///

src/types/callback_game.rs

@@ -3,8 +3,9 @@
 /// [The official docs](https://core.telegram.org/bots/api#callbackgame).
 use serde::{Deserialize, Serialize};
 
-/// A placeholder, currently holds no information. Use [@Botfather] to set up
-/// your game.
+/// A placeholder, currently holds no information.
+///
+/// Use [@Botfather] to set up your game.
 ///
 /// [@Botfather]:  https://t.me/botfather
 #[derive(Copy, Clone, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]

src/types/passport_element_error.rs

@@ -46,7 +46,9 @@ pub enum PassportElementErrorKind {
 }
 
 /// Represents an issue in one of the data fields that was provided by the
-/// user. The error is considered resolved when the field's value changes.
+/// user.
+///
+/// The error is considered resolved when the field's value changes.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrordatafield).
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize)]
@@ -61,9 +63,10 @@ pub struct PassportElementErrorDataField {
     pub data_hash: String,
 }
 
-/// Represents an issue with the front side of a document. The error is
-/// considered resolved when the file with the front side of the document
-/// changes.
+/// Represents an issue with the front side of a document.
+///
+/// The error is considered resolved when the file with the front side of the
+/// document changes.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrorfrontside).
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize)]
@@ -76,9 +79,10 @@ pub struct PassportElementErrorFrontSide {
     pub file_hash: String,
 }
 
-/// Represents an issue with the reverse side of a document. The error is
-/// considered resolved when the file with reverse side of the document
-/// changes.
+/// Represents an issue with the reverse side of a document.
+///
+/// The error is considered resolved when the file with reverse side of the
+/// document changes.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrorreverseside).
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize)]
@@ -91,8 +95,9 @@ pub struct PassportElementErrorReverseSide {
     pub file_hash: String,
 }
 
-//// Represents an issue with the selfie with a document. The error is
-//// considered resolved when the file with the selfie changes.
+//// Represents an issue with the selfie with a document.
+//
+/// The error is considered resolved when the file with the selfie changes.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrorselfie).
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize)]
@@ -104,8 +109,10 @@ pub struct PassportElementErrorSelfie {
     pub file_hash: String,
 }
 
-/// Represents an issue with a document scan. The error is considered
-/// resolved when the file with the document scan changes.
+/// Represents an issue with a document scan.
+///
+/// The error is considered resolved when the file with the document scan
+/// changes.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrorfile).
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize)]
@@ -117,8 +124,10 @@ pub struct PassportElementErrorFile {
     pub file_hash: String,
 }
 
-/// Represents an issue with a list of scans. The error is considered
-/// resolved when the list of files containing the scans changes.
+/// Represents an issue with a list of scans.
+///
+/// The error is considered resolved when the list of files containing the scans
+/// changes.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrorfiles).
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize)]
@@ -131,8 +140,9 @@ pub struct PassportElementErrorFiles {
 }
 
 /// Represents an issue with one of the files that constitute the
-/// translation of a document. The error is considered resolved when the
-/// file changes.
+/// translation of a document.
+///
+/// The error is considered resolved when the file changes.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrortranslationfile).
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize)]
@@ -145,8 +155,9 @@ pub struct PassportElementErrorTranslationFile {
     pub file_hash: String,
 }
 
-/// Represents an issue with the translated version of a document. The
-/// error is considered resolved when a file with the document translation
+/// Represents an issue with the translated version of a document.
+///
+/// The error is considered resolved when a file with the document translation
 /// change.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrortranslationfiles).
@@ -159,8 +170,9 @@ pub struct PassportElementErrorTranslationFiles {
     pub file_hashes: Vec<String>,
 }
 
-/// Represents an issue in an unspecified place. The error is considered
-/// resolved when new data is added.
+/// Represents an issue in an unspecified place.
+///
+/// The error is considered resolved when new data is added.
 ///
 /// [The official docs](https://core.telegram.org/bots/api#passportelementerrorunspecified).
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Serialize, Deserialize)]