Deprecate polling(), expose Polling{,Builder} and fix docs

src/dispatching/update_listeners.rs

@@ -42,8 +42,9 @@ use crate::{
 mod polling;
 mod stateful_listener;
 
+#[allow(deprecated)]
 pub use self::{
-    polling::{polling, polling_builder, polling_default, PollingBuilder},
+    polling::{polling, polling_builder, polling_default, Polling, PollingBuilder, PollingStream},
     stateful_listener::StatefulListener,
 };
 

src/dispatching/update_listeners/polling.rs

@@ -34,12 +34,20 @@ where
     R: Requester + Send + 'static,
     <R as Requester>::GetUpdates: Send,
 {
-    /// Set timeout.
+    /// A timeout in seconds for polling.
+    ///
+    /// ## Note
+    ///
+    /// `timeout` should not be bigger than http client timeout, see
+    /// [`default_reqwest_settings`] for default http client settings.
+    ///
+    /// [`default_reqwest_settings`]: crate::net::default_reqwest_settings
     pub fn timeout(self, timeout: Duration) -> Self {
         Self { timeout: Some(timeout), ..self }
     }
 
-    /// Set limit.
+    /// Limit the number of updates to be retrieved at once. Values between
+    /// 1—100 are accepted.
     ///
     /// ## Panics
     ///
@@ -51,14 +59,17 @@ where
         Self { limit: Some(limit), ..self }
     }
 
-    /// Set allowed updates.
+    /// A list of the types of updates you want to receive.
     ///
     /// ## Note
     ///
-    /// Teloxide normally (when using [`Dispatcher`] or repls) sets this
+    /// Teloxide normally (when using [`Dispatcher`] or [`repl`]s) sets this
-    /// automatically.
+    /// automatically via [`hint_allowed_updates`], so you rarely need to use
+    /// `allowed_updates` explicitly.
     ///
     /// [`Dispatcher`]: crate::dispatching::Dispatcher
+    /// [`repl`]: fn@crate::repl
+    /// [`hint_allowed_updates`]: crate::dispatching::update_listeners::UpdateListener::hint_allowed_updates
     pub fn allowed_updates(self, allowed_updates: Vec<AllowedUpdate>) -> Self {
         Self { allowed_updates: Some(allowed_updates), ..self }
     }
@@ -70,10 +81,14 @@ where
         self
     }
 
-    /// Creates a polling update listener.
+    /// Returns a long polling update listener with configuration from the
+    /// builder.
+    ///
+    /// See also: [`polling_default`], [`Polling`].
     pub fn build(self) -> Polling<R> {
         let Self { bot, timeout, limit, allowed_updates } = self;
-        polling(bot, timeout, limit, allowed_updates)
+        let (token, flag) = AsyncStopToken::new_pair();
+        Polling { bot, timeout, limit, allowed_updates, flag, token }
     }
 }
 
@@ -101,59 +116,77 @@ where
     polling_builder(bot).timeout(Duration::from_secs(10)).delete_webhook().await.build()
 }
 
-#[cfg_attr(doc, aquamarine::aquamarine)]
 /// Returns a long polling update listener with some additional options.
-///
+#[deprecated(since = "0.7.0", note = "use `polling_builder` instead")]
-/// - `bot`: Using this bot, the returned update listener will receive updates.
+pub fn polling<R>(
-/// - `timeout`: A timeout in seconds for polling.
+    bot: R,
-/// - `limit`: Limits the number of updates to be retrieved at once. Values
+    timeout: Option<Duration>,
-///   between 1—100 are accepted.
+    limit: Option<u8>,
-/// - `allowed_updates`: A list the types of updates you want to receive.
+    allowed_updates: Option<Vec<AllowedUpdate>>,
-///
+) -> Polling<R>
-/// See [`GetUpdates`] for defaults.
+where
-///
+    R: Requester + Send + 'static,
-/// See also: [`polling_default`](polling_default).
+    <R as Requester>::GetUpdates: Send,
-///
+{
-/// ## Notes
+    let mut builder = polling_builder(bot);
-///
+    builder.timeout = timeout;
-/// - `timeout` should not be bigger than http client timeout, see
+    builder.limit = limit;
-///   [`default_reqwest_settings`] for default http client settings.
+    builder.allowed_updates = allowed_updates;
-/// - [`repl`]s and [`Dispatcher`] use [`hint_allowed_updates`] to set
+    builder.build()
-///   `allowed_updates`, so you rarely need to pass `allowed_updates`
+}
-///   explicitly.
+
-///
+async fn delete_webhook_if_setup<R>(requester: &R)
-/// [`default_reqwest_settings`]: teloxide::net::default_reqwest_settings
+where
-/// [`repl`]: fn@crate::repl
+    R: Requester,
-/// [`Dispatcher`]: crate::dispatching::Dispatcher
+{
-/// [`hint_allowed_updates`]:
+    let webhook_info = match requester.get_webhook_info().send().await {
-/// crate::dispatching::update_listeners::UpdateListener::hint_allowed_updates
+        Ok(ok) => ok,
+        Err(e) => {
+            log::error!("Failed to get webhook info: {:?}", e);
+            return;
+        }
+    };
+
+    let is_webhook_setup = webhook_info.url.is_some();
+
+    if is_webhook_setup {
+        if let Err(e) = requester.delete_webhook().send().await {
+            log::error!("Failed to delete a webhook: {:?}", e);
+        }
+    }
+}
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+/// A polling update listener.
 ///
 /// ## How it works
 ///
-/// Long polling works by repeatedly calling [`Bot::get_updates`][get_updates].
+/// Long polling works by repeatedly calling
-/// If telegram has any updates, it returns them immediately, otherwise it waits
+/// [`Bot::get_updates`][get_updates]. If telegram has any updates, it
-/// until either it has any updates or `timeout` expires.
+/// returns them immediately, otherwise it waits until either it has any
+/// updates or `timeout` expires.
 ///
-/// Each [`get_updates`][get_updates] call includes an `offset` parameter equal
+/// Each [`get_updates`][get_updates] call includes an `offset` parameter
-/// to the latest update id + one, that allows to only receive updates that has
+/// equal to the latest update id + one, that allows to only receive
-/// not been received before.
+/// updates that has not been received before.
 ///
-/// When telegram receives a [`get_updates`][get_updates] request with `offset =
+/// When telegram receives a [`get_updates`][get_updates] request with
-/// N` it forgets any updates with id < `N`. When `polling` listener is stopped,
+/// `offset = N` it forgets any updates with id < `N`. When `polling`
-/// it sends [`get_updates`][get_updates] with `timeout = 0, limit = 1` and
+/// listener is stopped, it sends [`get_updates`][get_updates] with
-/// appropriate `offset`, so future bot restarts won't see updates that were
+/// `timeout = 0, limit = 1` and appropriate `offset`, so future bot
-/// already seen.
+/// restarts won't see updates that were already seen.
 ///
-/// Consumers of a `polling` update listener then need to repeatedly call
+/// Consumers of a [`Polling`] update listener then need to repeatedly call
 /// [`futures::StreamExt::next`] to get the updates.
 ///
-/// Here is an example diagram that shows these interactions between consumers
+/// Here is an example diagram that shows these interactions between
-/// like [`Dispatcher`], `polling` update listener and telegram.
+/// consumers like [`Dispatcher`], [`Polling`] update listener and
+/// telegram.
 ///
 /// ```mermaid
 /// sequenceDiagram    
 ///     participant C as Consumer
-///     participant P as polling
+///     participant P as Polling
 ///     participant T as Telegram
 ///
 ///     link C: Dispatcher @ ../struct.Dispatcher.html
@@ -193,41 +226,7 @@ where
 /// ```
 ///
 /// [get_updates]: crate::requests::Requester::get_updates
-pub fn polling<R>(
+/// [`Dispatcher`]: crate::dispatching::Dispatcher
-    bot: R,
-    timeout: Option<Duration>,
-    limit: Option<u8>,
-    allowed_updates: Option<Vec<AllowedUpdate>>,
-) -> Polling<R>
-where
-    R: Requester + Send + 'static,
-    <R as Requester>::GetUpdates: Send,
-{
-    let (token, flag) = AsyncStopToken::new_pair();
-    Polling { bot, timeout, limit, allowed_updates, flag, token }
-}
-
-async fn delete_webhook_if_setup<R>(requester: &R)
-where
-    R: Requester,
-{
-    let webhook_info = match requester.get_webhook_info().send().await {
-        Ok(ok) => ok,
-        Err(e) => {
-            log::error!("Failed to get webhook info: {:?}", e);
-            return;
-        }
-    };
-
-    let is_webhook_setup = webhook_info.url.is_some();
-
-    if is_webhook_setup {
-        if let Err(e) = requester.delete_webhook().send().await {
-            log::error!("Failed to delete a webhook: {:?}", e);
-        }
-    }
-}
-
 pub struct Polling<B: Requester> {
     bot: B,
     timeout: Option<Duration>,
@@ -370,6 +369,7 @@ fn polling_is_send() {
     use crate::dispatching::update_listeners::AsUpdateStream;
 
     let bot = crate::Bot::new("TOKEN");
+    #[allow(deprecated)]
     let mut polling = polling(bot, None, None, None);
 
     assert_send(&polling);