Merge pull request #305 from elpiel/doc-cfg-annotation-to-cfg-items

add doc(cfg) attributes

Cargo.toml

@@ -32,7 +32,7 @@ frunk- = ["frunk"]
 
 macros = ["teloxide-macros"]
 
-nightly = [] # currently used only for `README.md` tests
+nightly = [] # currently used for `README.md` tests and building docs for `docsrs` to add `This is supported on feature="..." only.`
 
 [dependencies]
 serde_json = "1.0.55"
@@ -68,8 +68,9 @@ pretty_env_logger = "0.4.0"
 lazy_static = "1.4.0"
 tokio = { version = "0.2.21", features = ["fs", "stream", "rt-threaded", "macros"] }
 
-[package.metadata."docs.rs"]
+[package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
 
 [[test]]
 name = "redis"

src/bot/download.rs

@@ -56,6 +56,8 @@ impl Bot {
     /// [`tokio::fs::File`]: tokio::fs::File
     /// [`Bot::download_file`]: crate::Bot::download_file
     #[cfg(feature = "unstable-stream")]
+    // FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+    #[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "unstable-stream")))]
     pub async fn download_file_stream(
         &self,
         path: &str,

src/dispatching/dialogue/mod.rs

@@ -158,10 +158,13 @@ pub use transition::{
 };
 
 #[cfg(feature = "macros")]
-#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "macros")))]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "macros")))]
 pub use teloxide_macros::Transition;
 
 #[cfg(feature = "redis-storage")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "redis-storage")))]
 pub use storage::{RedisStorage, RedisStorageError};
 
 pub use storage::{serializer, InMemStorage, Serializer, Storage};

src/dispatching/dialogue/storage/mod.rs

@@ -9,6 +9,8 @@ use futures::future::BoxFuture;
 
 pub use in_mem_storage::InMemStorage;
 #[cfg(feature = "redis-storage")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "redis-storage")))]
 pub use redis_storage::{RedisStorage, RedisStorageError};
 pub use serializer::Serializer;
 use std::sync::Arc;

src/dispatching/dialogue/storage/serializer.rs

@@ -32,9 +32,13 @@ where
 ///
 /// [CBOR]: https://en.wikipedia.org/wiki/CBOR
 #[cfg(feature = "cbor-serializer")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "cbor-serializer")))]
 pub struct CBOR;
 
 #[cfg(feature = "cbor-serializer")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "cbor-serializer")))]
 impl<D> Serializer<D> for CBOR
 where
     D: Serialize + DeserializeOwned,
@@ -54,9 +58,13 @@ where
 ///
 /// [Bincode]: https://github.com/servo/bincode
 #[cfg(feature = "bincode-serializer")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "bincode-serializer")))]
 pub struct Bincode;
 
 #[cfg(feature = "bincode-serializer")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "bincode-serializer")))]
 impl<D> Serializer<D> for Bincode
 where
     D: Serialize + DeserializeOwned,

src/lib.rs

@@ -41,7 +41,15 @@
 #![allow(clippy::match_bool)]
 #![forbid(unsafe_code)]
 #![cfg_attr(all(feature = "nightly", doctest), feature(external_doc))]
-#![cfg_attr(all(docsrs, feature = "nightly"), feature(doc_cfg))]
+// we pass "--cfg docsrs" when building docs to add `This is supported on feature="..." only.`
+//
+// To properly build docs of this crate run
+// ```console
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+// $ RUSTDOCFLAGS="--cfg teloxide_docsrs" cargo +nightly doc --open --all-features
+// ```
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#![cfg_attr(all(teloxide_docsrs, feature = "nightly"), feature(doc_cfg))]
 
 pub use bot::{Bot, BotBuilder};
 pub use dispatching::repls::{
@@ -63,10 +71,8 @@ pub mod types;
 pub mod utils;
 
 #[cfg(feature = "macros")]
-extern crate teloxide_macros;
-
-#[cfg(feature = "macros")]
-#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "macros")))]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "macros")))]
 pub use teloxide_macros::teloxide;
 
 #[cfg(all(feature = "nightly", doctest))]

src/net/download.rs

@@ -28,6 +28,8 @@ where
 }
 
 #[cfg(feature = "unstable-stream")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "unstable-stream")))]
 pub async fn download_file_stream(
     client: &Client,
     token: &str,

src/net/mod.rs

@@ -1,4 +1,6 @@
 #[cfg(feature = "unstable-stream")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "unstable-stream")))]
 pub use download::download_file_stream;
 
 pub use self::{

src/prelude.rs

@@ -15,6 +15,8 @@ pub use crate::{
 };
 
 #[cfg(feature = "frunk")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "frunk")))]
 pub use crate::utils::UpState;
 
 pub use tokio::sync::mpsc::UnboundedReceiver;

src/utils/command.rs

@@ -50,7 +50,8 @@ use serde::export::Formatter;
 use std::{error::Error, fmt::Display};
 
 #[cfg(feature = "macros")]
-#[cfg_attr(all(docsrs, feature = "nightly"), doc(cfg(feature = "macros")))]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "macros")))]
 pub use teloxide_macros::BotCommand;
 
 /// An enumeration of bot's commands.

src/utils/mod.rs

@@ -9,4 +9,6 @@ mod up_state;
 pub use client_from_env::client_from_env;
 
 #[cfg(feature = "frunk")]
+// FIXME(waffle): use `docsrs` here when issue with combine is resolved <https://github.com/teloxide/teloxide/pull/305#issuecomment-716172103>
+#[cfg_attr(all(teloxide_docsrs, feature = "nightly"), doc(cfg(feature = "frunk")))]
 pub use up_state::UpState;