Apply suggestions from code review

src/dispatching/repls.rs

@@ -1,9 +1,9 @@
 //! [REPL]s for dispatching updates.
 //!
-//! This module provides functions for easy update handling, that accept a
+//! This module provides utilities for easy update handling. They accept a
 //! single "handler" function that processes all updates of a certain kind. Note
-//! that REPLs are meant to be used as a prototyping tool and lack configuration
+//! that REPLs are meant to be used for simple scenarios, such as prototyping,
-//! and some advanced features.
+//! inasmuch they lack configuration and some advanced features.
 //!
 //! [REPL]: https://en.wikipedia.org/wiki/Read-eval-print_loop
 

src/dispatching/repls/commands_repl.rs

@@ -22,19 +22,17 @@ use teloxide_core::requests::Requester;
 /// Don't be scared by many trait bounds in the signature, in essence they
 /// require:
 ///
-/// 1. `bot` is a bot, client for the Telegram bot API
+/// 1. `bot` is a bot, client for the Telegram bot API. It is represented via
-///    - in teloxide this is represented via a [`Requester`] trait
+///    the [`Requester`] trait.
-/// 2. `handler` is an async function that returns `Result<(), E>`
+/// 2. `handler` is an `async` function that takes arguments from
-///    - Such that `E` can be printed with [`Debug`] formatting
+///    [`DependencyMap`] (see below) and returns [`ResponseResult`].
-///    - And all arguments can be extracted from [`DependencyMap`]
+/// 3. `cmd` is a type hint for your command enumeration
-///       - Which is the same, as all arguments implementing `Send + Sync +
+///    `MyCommand`: just write `MyCommand::ty()`. Note that `MyCommand` must
-///         'static`
+///    implement the [`BotCommands`] trait, typically via
-/// 3. `cmd` is a type of the command that will be parsed,
+///   `#[derive(BotCommands)]`.
-///    - The command type must implement [`BotCommands`] trait
-///    - It can be acquired by writing `TheCommandType::ty()`
 ///
-/// All other requirements are about thread safety and data validity and can be
+/// All the other requirements are about thread safety and data validity and can
-/// ignored for most of the time.
+/// be ignored for most of the time.
 ///
 /// ## Handler arguments
 ///
@@ -85,20 +83,18 @@ where
 /// Don't be scared by many trait bounds in the signature, in essence they
 /// require:
 ///
-/// 1. `bot` is a bot, client for the Telegram bot API
+/// 1. `bot` is a bot, client for the Telegram bot API. It is represented via
-///    - in teloxide this is represented via a [`Requester`] trait
+///    the [`Requester`] trait.
-/// 2. `handler` is an async function that returns `Result<(), E>`
+/// 2. `handler` is an `async` function that takes arguments from
-///    - Such that `E` can be printed with [`Debug`] formatting
+///    [`DependencyMap`] (see below) and returns [`ResponseResult`].
-///    - And all arguments can be extracted from [`DependencyMap`]
+/// 3. `listener` is something that takes updates from a Telegram server and
-///       - Which is the same, as all arguments implementing `Send + Sync +
+///    implements [`UpdateListener`].
-///         'static`
+/// 4. `cmd` is a type hint for your command enumeration `MyCommand`: just
-/// 3. `listener` is an [`UpdateListener`]
+///    write `MyCommand::ty()`. Note that `MyCommand` must implement the
-/// 4. `cmd` is a type of the command that will be parsed,
+///   [`BotCommands`] trait, typically via `#[derive(BotCommands)]`.
-///    - The command type must implement [`BotCommands`] trait
-///    - It can be acquired by writing `TheCommandType::ty()`
 ///
-/// All other requirements are about thread safety and data validity and can be
+/// All the other requirements are about thread safety and data validity and can
-/// ignored for most of the time.
+/// be ignored for most of the time.
 ///
 /// ## Handler arguments
 ///

src/dispatching/repls/repl.rs

@@ -19,13 +19,10 @@ use teloxide_core::requests::Requester;
 /// Don't be scared by many trait bounds in the signature, in essence they
 /// require:
 ///
-/// 1. `bot` is a bot, client for the Telegram bot API
+/// 1. `bot` is a bot, client for the Telegram bot API. It is represented via
-///    - in teloxide this is represented via a [`Requester`] trait
+///    the [`Requester`] trait.
-/// 2. `handler` is an async function that returns `Result<(), E>`
+/// 2. `handler` is an `async` function that takes arguments from
-///    - Such that `E` can be printed with [`Debug`] formatting
+///    [`DependencyMap`] (see below) and returns [`ResponseResult`].
-///    - And all arguments can be extracted from [`DependencyMap`]
-///       - Which is the same, as all arguments implementing `Send + Sync +
-///         'static`
 ///
 /// ## Handler arguments
 ///
@@ -68,14 +65,12 @@ where
 /// Don't be scared by many trait bounds in the signature, in essence they
 /// require:
 ///
-/// 1. `bot` is a bot, client for the Telegram bot API
+/// 1. `bot` is a bot, client for the Telegram bot API. It is represented via
-///    - in teloxide this is represented via a [`Requester`] trait
+///    the [`Requester`] trait.
-/// 2. `handler` is an async function that returns `Result<(), E>`
+/// 2. `handler` is an `async` function that takes arguments from
-///    - Such that `E` can be printed with [`Debug`] formatting
+///    [`DependencyMap`] (see below) and returns [`ResponseResult`].
-///    - And all arguments can be extracted from [`DependencyMap`]
+/// 3. `listener` is something that takes updates from a Telegram server and
-///       - Which is the same, as all arguments implementing `Send + Sync +
+///    implements [`UpdateListener`].
-///         'static`
-/// 3. `listener` is an [`UpdateListener`]
 ///
 /// ## Handler arguments
 ///

src/dispatching/repls/stopping.md

@@ -1,4 +1,4 @@
-To stop repl, simply press `Ctrl`+`C` in the terminal where you run the program.
+To stop a REPL, simply press `Ctrl`+`C` in the terminal where you run the program.
-Note that gracefully stopping can take some time (we plan to improve this, see [#711]).
+Note that graceful shutdown may take some time (we plan to improve this, see [#711]).
 
 [#711]: https://github.com/teloxide/teloxide/issues/711