Merge pull request #1022 from teloxide/improve-terminatedbyothergetupdates-docs

improve `ApiError::TerminatedByOtherGetUpdates` docs

crates/teloxide-core/src/errors.rs

@@ -677,8 +677,12 @@ impl_api_error! {
         /// [`SendMessage`]: crate::payloads::SendMessage
         WrongHttpUrl = "Bad Request: wrong HTTP URL",
 
-        /// Occurs when bot tries GetUpdate before the timeout. Make sure that only
-        /// one Updater is running.
+        /// Occurs when multiple [`GetUpdates`] calls happen at the same time.
+        ///
+        /// This can happen if
+        /// 1. You are running multiple bot instances
+        /// 2. You are running multiple update consumers (like `Dispatcher` or `repl`)
+        /// 3. You are calling [`GetUpdates`] yourself and the second call is done before the first one finishes
         ///
         /// May happen in methods:
         /// 1. [`GetUpdates`]

crates/teloxide/src/update_listeners.rs

@@ -63,7 +63,7 @@ pub trait UpdateListener:
     type Err;
 
     /// Returns a token which stops this listener.
-    ///  
+    ///
     /// The [`stop`] function of the token is not guaranteed to have an
     /// immediate effect. That is, some listeners can return updates even
     /// after [`stop`] is called (e.g.: because of buffering).

crates/teloxide/src/update_listeners/polling.rs

@@ -195,20 +195,20 @@ where
 /// telegram.
 ///
 /// ```mermaid
-/// sequenceDiagram    
+/// sequenceDiagram
 ///     participant C as Consumer
 ///     participant P as Polling
 ///     participant T as Telegram
 ///
 ///     link C: Dispatcher @ ../struct.Dispatcher.html
 ///     link C: repl @ ../../fn.repl.html
-///     
+///
 ///     C->>P: next
 ///
 ///     P->>+T: Updates? (offset = 0)
 ///     Note right of T: timeout
 ///     T->>-P: None
-///     
+///
 ///     P->>+T: Updates? (offset = 0)
 ///     Note right of T: <= timeout
 ///     T->>-P: updates with ids [3, 4]
@@ -217,10 +217,10 @@ where
 ///
 ///     C->>P: next
 ///     P->>C: update(4)
-///     
+///
 ///     C->>P: next
 ///
-///     P->>+T: Updates? (offset = 5)    
+///     P->>+T: Updates? (offset = 5)
 ///     Note right of T: <= timeout
 ///     T->>-P: updates with ids [5]
 ///