From b5f98dd46260f4504d424a00f39fcd49b07643d6 Mon Sep 17 00:00:00 2001
From: Waffle <wafflewafflerov@gmail.com>
Date: Wed, 9 Oct 2019 21:17:45 +0300
Subject: [PATCH] Add doc comment for updater trait

---
 src/bot/api.rs            |  3 +-
 src/dispatcher/updater.rs | 89 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 88 insertions(+), 4 deletions(-)

diff --git a/src/bot/api.rs b/src/bot/api.rs
index 52d8a409..0472d84d 100644
--- a/src/bot/api.rs
+++ b/src/bot/api.rs
@@ -1,10 +1,9 @@
-use crate::requests::get_updates::GetUpdates;
 use crate::{
     bot::Bot,
     requests::{
         ChatId, EditMessageLiveLocation, ForwardMessage, GetFile, GetMe,
         SendAudio, SendLocation, SendMediaGroup, SendMessage, SendPhoto,
-        StopMessageLiveLocation,
+        StopMessageLiveLocation, GetUpdates
     },
     types::{InputFile, InputMedia},
 };
diff --git a/src/dispatcher/updater.rs b/src/dispatcher/updater.rs
index 6574b738..8dd14da1 100644
--- a/src/dispatcher/updater.rs
+++ b/src/dispatcher/updater.rs
@@ -8,12 +8,97 @@ use futures::{Stream, StreamExt, stream};
 
 use crate::{
     bot::Bot,
-    requests::Request,
     types::Update,
     RequestError,
 };
 
 // Currently just a placeholder, but I'll  add here some methods
+/// Updater is stream of updates.
+///
+/// Telegram supports 2 ways of [getting updates]: [long polling](Long Polling) and webhook
+///
+/// ## Long Polling
+///
+/// In long polling ([wiki]) you just call [GetUpdates] every N seconds.
+///
+/// #### Example:
+///
+/// <pre>
+///     tg                           bot
+///      |                            |
+///      |<---------------------------| Updates? (GetUpdates call)
+///      ↑                            ↑
+///      |          timeout<a id="1b" href="#1">^1</a>         |
+///      ↓                            ↓
+/// Nope |--------------------------->|
+///      ↑                            ↑
+///      | delay between GetUpdates<a id="2b" href="#2">^2</a> |
+///      ↓                            ↓
+///      |<---------------------------| Updates?
+///      ↑                            ↑
+///      |          timeout<a id="3b" href="#3">^3</a>         |
+///      ↓                            ↓
+/// Yes  |-------[updates 0, 1]------>|
+///      ↑                            ↑
+///      |           delay            |
+///      ↓                            ↓
+///      |<-------[offset = 1]--------| Updates?<a id="4b" href="#4">^4</a>
+///      ↑                            ↑
+///      |           timeout          |
+///      ↓                            ↓
+/// Yes  |---------[update 2]-------->|
+///      ↑                            ↑
+///      |           delay            |
+///      ↓                            ↓
+///      |<-------[offset = 2]--------| Updates?
+///      ↑                            ↑
+///      |           timeout          |
+///      ↓                            ↓
+/// Nope |--------------------------->|
+///      ↑                            ↑
+///      |           delay            |
+///      ↓                            ↓
+///      |<-------[offset = 2]--------| Updates?
+///      ↑                            ↑
+///      |           timeout          |
+///      ↓                            ↓
+/// Nope |--------------------------->|
+///      ↑                            ↑
+///      |           delay            |
+///      ↓                            ↓
+///      |<-------[offset = 2]--------| Updates?
+///      ↑                            ↑
+///      |           timeout          |
+///      ↓                            ↓
+/// Yes  |-------[updates 2..5]------>|
+///      ↑                            ↑
+///      |           delay            |
+///      ↓                            ↓
+///      |<-------[offset = 5]--------| Updates?
+///      ↑                            ↑
+///      |           timeout          |
+///      ↓                            ↓
+/// Nope |--------------------------->|
+///      |                            |
+///      ~    and so on, and so on    ~
+/// </pre>
+///
+/// <a id="1" href="#1b">^1</a> Timeout can be even 0
+///   (this is also called short polling),
+///   but you should use it **only** for testing purposes
+///
+/// <a id="2" href="#2b">^2</a> Large delays will cause in bot lags,
+///   so delay shouldn't exceed second.
+///
+/// <a id="3" href="#3b">^3</a> Note that if telegram already have updates for
+///   you it will answer you **without** waiting for a timeout
+///
+/// <a id="4" href="#4b">^4</a> `offset = N` means that we've already received
+///   updates `0..=N`
+///
+/// [GetUpdates]: crate::requests::GetUpdates
+/// [getting updates]: https://core.telegram.org/bots/api#getting-updates
+/// [wiki]: https://en.wikipedia.org/wiki/Push_technology#Long_polling
 pub trait Updater<E>: Stream<Item=Result<Update, E>> {}
 
 #[pin_project]
@@ -38,7 +123,7 @@ impl<S, E> Stream for StreamUpdater<S> where S: Stream<Item=Result<Update, E>> {
 
 impl<S, E> Updater<E> for StreamUpdater<S> where S: Stream<Item=Result<Update, E>> {}
 
-pub fn polling<'a>(bot: &'a Bot) -> impl Updater<RequestError> + 'a/*StreamUpdater<impl Stream<Item=ResponseResult<Update>> + 'a>*/ {
+pub fn polling<'a>(bot: &'a Bot) -> impl Updater<RequestError> + 'a {
     let stream = stream::unfold((bot, 0), |(bot, mut offset)| async move {
         // this match converts Result<Vec<_>, _> -> Vec<Result<_, _>>
         let updates = match bot.get_updates().offset(offset).send().await {