Merge pull request #14 from teloxide/adaptor_features

Adaptors features, module, docs

Cargo.toml

@@ -39,9 +39,25 @@ never = "0.1.0"
 vecrem = { git = "https://github.com/WaffleLapkin/vecrem", rev = "6b9b6f42342df8b75548c6ed387072ff235429b1" }
 
 [features]
-# features those require nightly compiler
+default = []
+
+# Features which require nightly compiler.
+#
+# Currently the only used compiler feature is feature(type_alias_impl_trait)
+# which allow implementing `Future`s without boxing.
 nightly = []
 
+# Throttling bot adaptor
+throttle = []
+
+# CacheMe bot adaptor
+cache_me = []
+
+# AutoSend bot adaptor
+auto_send = []
+
+full = ["throttle", "cache_me", "auto_send"]
+
 [package.metadata."docs.rs"]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]

src/adaptors.rs

@@ -0,0 +1,32 @@
+//! ## Bot adaptors
+//!
+//! Bot adaptors are very similar to [`Iterator`] adaptors —
+//! they are bots (implement [`Requester`]) which wrap other bots
+//! adding new functionality.
+//!
+//! E.g. [`AutoSend`] allows `await`ing requests directly,
+//! without need to use `.send()`.
+//!
+//! [`Requester`]: crate::requests::Requester
+
+#[cfg(feature = "auto_send")]
+#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "auto_send")))]
+pub mod auto_send;
+#[cfg(feature = "cache_me")]
+#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "cache_me")))]
+pub mod cache_me;
+#[cfg(feature = "throttle")]
+#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "throttle")))]
+pub mod throttle;
+
+#[cfg(feature = "auto_send")]
+#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "auto_send")))]
+pub use auto_send::AutoSend;
+#[cfg(feature = "cache_me")]
+#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "cache_me")))]
+pub use cache_me::CacheMe;
+#[cfg(feature = "throttle")]
+#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "throttle")))]
+pub use throttle::Throttle;
+
+// FIXME: move default `parse_mode` to adaptor

src/adaptors/throttle.rs

@@ -18,7 +18,7 @@ use tokio::{
 use vecrem::VecExt;
 
 use crate::{
-    bot::limits::chan_send::{ChanSend, SendTy},
+    adaptors::throttle::chan_send::{ChanSend, SendTy},
     payloads::SendMessage,
     requests::{HasPayload, Output, Request, Requester},
     types::ChatId,
@@ -123,7 +123,7 @@ impl Default for Limits {
 /// ## Examples
 ///
 /// ```no_run (throttle fails to spawn task without tokio runtime)
-/// use teloxide_core::{bot::Limits, requests::RequesterExt, Bot};
+/// use teloxide_core::{adaptors::throttle::Limits, requests::RequesterExt, Bot};
 ///
 /// # #[allow(deprecated)]
 /// let bot = Bot::new("TOKEN").throttle(Limits::default());
@@ -316,6 +316,8 @@ impl<B> Throttle<B> {
     /// Creates new [`Throttle`] spawning the worker with `tokio::spawn`
     ///
     /// Note: it's recommended to use [`RequesterExt::throttle`] instead.
+    ///
+    /// [`RequesterExt::throttle`]: crate::requests::RequesterExt::throttle
     pub fn new_spawn(bot: B, limits: Limits) -> Self
     where
         // Basically, I hate this bound.
@@ -613,7 +615,7 @@ mod chan_send {
     use never::Never;
     use tokio::sync::{mpsc, mpsc::error::SendError, oneshot::Sender};
 
-    use crate::bot::limits::Id;
+    use crate::adaptors::throttle::Id;
 
     pub(super) trait SendTy {
         fn send_t(self, val: (Id, Sender<Never>)) -> ChanSend;

src/bot/download.rs

@@ -1,11 +1,11 @@
-use tokio::io::AsyncWrite;
+use bytes::Bytes;
+use tokio::{io::AsyncWrite, stream::Stream};
 
-#[cfg(feature = "unstable-stream")]
-use ::{bytes::Bytes, tokio::stream::Stream};
-
-#[cfg(feature = "unstable-stream")]
-use crate::net::download_file_stream;
-use crate::{bot::Bot, net::download_file, DownloadError};
+use crate::{
+    bot::Bot,
+    net::{download_file, download_file_stream},
+    DownloadError,
+};
 
 impl Bot {
     /// Download a file from Telegram into `destination`.
@@ -55,7 +55,6 @@ impl Bot {
     /// [`AsyncWrite`]: tokio::io::AsyncWrite
     /// [`tokio::fs::File`]: tokio::fs::File
     /// [`Bot::download_file`]: crate::Bot::download_file
-    #[cfg(feature = "unstable-stream")]
     pub async fn download_file_stream(
         &self,
         path: &str,

src/bot/mod.rs

@@ -14,14 +14,7 @@ use crate::{
 };
 
 mod api;
-mod auto_send;
-mod cache_me;
 mod download;
-mod limits;
-
-pub use auto_send::AutoSend;
-pub use cache_me::CacheMe;
-pub use limits::{Limits, Throttle};
 
 pub(crate) const TELOXIDE_TOKEN: &str = "TELOXIDE_TOKEN";
 pub(crate) const TELOXIDE_PROXY: &str = "TELOXIDE_PROXY";

src/lib.rs

@@ -10,6 +10,7 @@
 #![cfg_attr(all(docsrs, feature = "nightly"), feature(doc_cfg, doc_spotlight))]
 #![cfg_attr(feature = "nightly", feature(type_alias_impl_trait))]
 #![forbid(unsafe_code)]
+#![cfg_attr(feature = "full", deny(broken_intra_doc_links))]
 //#![deny(missing_docs)]
 
 #[macro_use]
@@ -18,20 +19,18 @@ mod local_macros;
 
 // FIXME(waffle): rethink modules, find a place for wrappers.
 pub use self::{
-    bot::{AutoSend, Bot, BotBuilder, CacheMe},
+    bot::{Bot, BotBuilder},
     errors::{ApiError, DownloadError, RequestError},
 };
 
+pub mod adaptors;
 pub mod payloads;
 pub mod prelude;
 pub mod requests;
 pub mod types;
 
-// FIXME(waffle): made `pub` to reexport bot wrappers, in future we may want to
-//                reexport them from elsewhere
-pub mod bot;
-
 // reexported
+mod bot;
 mod errors;
 
 // implementation details

src/net/download.rs

@@ -27,12 +27,11 @@ where
     Ok(())
 }
 
-#[cfg(feature = "unstable-stream")]
 pub async fn download_file_stream(
     client: &Client,
     token: &str,
     path: &str,
-) -> Result<impl Stream<Item = reqwest::Result<Bytes>>, reqwest::Error> {
+) -> Result<impl futures::Stream<Item = reqwest::Result<bytes::Bytes>>, reqwest::Error> {
     let res = client
         .get(&super::file_url(TELEGRAM_API_URL, token, path))
         .send()

src/net/mod.rs

@@ -1,8 +1,5 @@
-#[cfg(feature = "unstable-stream")]
-pub(crate) use download::download_file_stream;
-
 pub(crate) use self::{
-    download::download_file,
+    download::{download_file, download_file_stream},
     request::{request_json, request_json2, request_multipart, request_multipart2},
     telegram_response::TelegramResponse,
 };

src/payloads/mod.rs

@@ -1,3 +1,4 @@
+/// Payloads - data types sended to relegram
 pub mod setters;
 
 mod get_me;

src/prelude.rs

@@ -1 +1,3 @@
+//! Crate prelude
+
 pub use crate::requests::Requester;

src/requests/mod.rs

@@ -1,4 +1,4 @@
-//! API requests.
+//! Telegram API requests.
 
 mod has_payload;
 mod payload;

src/requests/request.rs

@@ -14,6 +14,8 @@ use crate::requests::{HasPayload, Output};
 /// This is crucial for request wrappers which may want to cancel and/or never
 /// send the underlying request. E.g.: [`Throttle<B>`]'s `send_ref` calls
 /// `B::send_ref` while _not_ meaning to really send the request right now.
+///
+/// [`Throttle<B>`]: crate::adaptors::Throttle
 #[cfg_attr(all(docsrs, feature = "nightly"), doc(spotlight))]
 pub trait Request: HasPayload {
     /*

src/requests/requester.rs

@@ -4,7 +4,7 @@ use crate::{
     types::ChatId,
 };
 
-/// The trait implemented by all bots & bot wrappers.
+/// The trait implemented by all bots & bot adaptors.
 /// Essentially a request builder factory (?).
 ///
 /// _This trait is included in the crate's [`prelude`](crate::prelude)_.

src/requests/requester_ext.rs

@@ -1,11 +1,20 @@
-use crate::{
-    bot::{CacheMe, Limits, Throttle},
-    requests::Requester,
-    AutoSend,
-};
+use crate::requests::Requester;
+
+#[cfg(feature = "cache_me")]
+use crate::adaptors::CacheMe;
+
+#[cfg(feature = "auto_send")]
+use crate::adaptors::AutoSend;
+
+#[cfg(feature = "throttle")]
+use crate::adaptors::throttle::{Limits, Throttle};
 
 pub trait RequesterExt: Requester {
     /// Add `get_me` caching ability, see [`CacheMe`] for more.
+    ///
+    /// [`CacheMe`]:
+    #[cfg(feature = "cache_me")]
+    #[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "cache_me")))]
     fn cache_me(self) -> CacheMe<Self>
     where
         Self: Sized,
@@ -14,6 +23,8 @@ pub trait RequesterExt: Requester {
     }
 
     /// Send requests automatically, see [`AutoSend`] for more.
+    #[cfg(feature = "auto_send")]
+    #[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "auto_send")))]
     fn auto_send(self) -> AutoSend<Self>
     where
         Self: Sized,
@@ -24,6 +35,8 @@ pub trait RequesterExt: Requester {
     /// Add throttling ability, see [`Throttle`] for more.
     ///
     /// Note: this spawns the worker, just as [`Throttle::new_spawn`].
+    #[cfg(feature = "throttle")]
+    #[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "throttle")))]
     fn throttle(self, limits: Limits) -> Throttle<Self>
     where
         Self: Sized,

src/types/chat_member.rs

@@ -27,14 +27,14 @@ pub enum ChatMemberKind {
     Kicked(Kicked),
 }
 
-/// Creator of the group. This struct is part of the [`ChatmemberKind`] enum.
+/// Creator of the group. This struct is part of the [`ChatMemberKind`] enum.
 #[derive(Clone, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
 pub struct Creator {
     /// Custom title for this user.
     pub custom_title: Option<String>,
 }
 
-/// Administrator of the group. This struct is part of the [`ChatmemberKind`]
+/// Administrator of the group. This struct is part of the [`ChatMemberKind`]
 /// enum.
 #[derive(Clone, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
 pub struct Administrator {
@@ -81,7 +81,7 @@ pub struct Administrator {
     pub can_promote_members: bool,
 }
 
-/// User, restricted in the group. This struct is part of the [`ChatmemberKind`]
+/// User, restricted in the group. This struct is part of the [`ChatMemberKind`]
 /// enum.
 #[derive(Clone, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
 pub struct Restricted {
@@ -106,7 +106,7 @@ pub struct Restricted {
     pub can_add_web_page_previews: bool,
 }
 
-/// User kicked from the group. This struct is part of the [`ChatmemberKind`]
+/// User kicked from the group. This struct is part of the [`ChatMemberKind`]
 /// enum.
 #[derive(Clone, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
 pub struct Kicked {

src/types/mod.rs

@@ -1,4 +1,4 @@
-//! API types.
+//! Telergam API types.
 
 pub use allowed_update::*;
 pub use animation::*;