generate docs for feature gated items (#1332)

* generate docs for feature-gated items on crates.io

* add newline in Cargo.toml

* unify newlines

* fix clippy

* introduce macros for features

* commit missing file

* Update subxt/src/lib.rs

* make it compile

subxt/src/backend/rpc/mod.rs

@@ -56,8 +56,9 @@
 // with other file names for their types.
 #![allow(clippy::module_inception)]
 
-#[cfg(feature = "jsonrpsee")]
-mod jsonrpsee_impl;
+crate::macros::cfg_jsonrpsee! {
+    mod jsonrpsee_impl;
+}
 
 mod rpc_client;
 mod rpc_client_t;

subxt/src/backend/rpc/rpc_client.rs

@@ -19,6 +19,7 @@ pub struct RpcClient {
 
 impl RpcClient {
     #[cfg(feature = "jsonrpsee")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "jsonrpsee")))]
     /// Create a default RPC client pointed at some URL, currently based on [`jsonrpsee`].
     ///
     /// Errors if an insecure URL is provided. In this case, use [`RpcClient::from_insecure_url`] instead.

subxt/src/client/light_client/builder.rs

@@ -5,6 +5,7 @@
 use super::{rpc::LightClientRpc, LightClient, LightClientError};
 use crate::backend::rpc::RpcClient;
 use crate::client::RawLightClient;
+use crate::macros::{cfg_jsonrpsee_native, cfg_jsonrpsee_web};
 use crate::utils::validate_url_is_secure;
 use crate::{config::Config, error::Error, OnlineClient};
 use std::num::NonZeroU32;
@@ -101,6 +102,7 @@ impl<T: Config> LightClientBuilder<T> {
     /// If smoldot panics, then the promise created will be leaked. For more details, see
     /// https://docs.rs/wasm-bindgen-futures/latest/wasm_bindgen_futures/fn.future_to_promise.html.
     #[cfg(feature = "jsonrpsee")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "jsonrpsee")))]
     pub async fn build_from_url<Url: AsRef<str>>(self, url: Url) -> Result<LightClient<T>, Error> {
         validate_url_is_secure(url.as_ref())?;
         self.build_from_insecure_url(url).await
@@ -255,58 +257,60 @@ async fn fetch_url(url: impl AsRef<str>) -> Result<serde_json::Value, Error> {
         .map_err(|err| Error::Rpc(crate::error::RpcError::ClientError(Box::new(err))))
 }
 
-#[cfg(all(feature = "jsonrpsee", feature = "native"))]
-mod jsonrpsee_helpers {
-    use crate::error::{Error, LightClientError};
-    use tokio_util::compat::Compat;
+cfg_jsonrpsee_native! {
+    mod jsonrpsee_helpers {
+        use crate::error::{Error, LightClientError};
+        use tokio_util::compat::Compat;
 
-    pub use jsonrpsee::{
-        client_transport::ws::{self, EitherStream, Url, WsTransportClientBuilder},
-        core::client::Client,
-    };
+        pub use jsonrpsee::{
+            client_transport::ws::{self, EitherStream, Url, WsTransportClientBuilder},
+            core::client::Client,
+        };
 
-    pub type Sender = ws::Sender<Compat<EitherStream>>;
-    pub type Receiver = ws::Receiver<Compat<EitherStream>>;
+        pub type Sender = ws::Sender<Compat<EitherStream>>;
+        pub type Receiver = ws::Receiver<Compat<EitherStream>>;
 
-    /// Build WS RPC client from URL
-    pub async fn client(url: &str) -> Result<Client, Error> {
-        let url = Url::parse(url).map_err(|_| Error::LightClient(LightClientError::InvalidUrl))?;
+        /// Build WS RPC client from URL
+        pub async fn client(url: &str) -> Result<Client, Error> {
+            let url = Url::parse(url).map_err(|_| Error::LightClient(LightClientError::InvalidUrl))?;
 
-        if url.scheme() != "ws" && url.scheme() != "wss" {
-            return Err(Error::LightClient(LightClientError::InvalidScheme));
+                if url.scheme() != "ws" && url.scheme() != "wss" {
+                    return Err(Error::LightClient(LightClientError::InvalidScheme));
+                }
+
+                let (sender, receiver) = ws_transport(url).await?;
+
+                Ok(Client::builder()
+                .max_buffer_capacity_per_subscription(4096)
+                .build_with_tokio(sender, receiver))
+            }
+
+            async fn ws_transport(url: Url) -> Result<(Sender, Receiver), Error> {
+                WsTransportClientBuilder::default()
+                    .build(url)
+                    .await
+                    .map_err(|_| Error::LightClient(LightClientError::Handshake))
+            }
         }
-
-        let (sender, receiver) = ws_transport(url).await?;
-
-        Ok(Client::builder()
-            .max_buffer_capacity_per_subscription(4096)
-            .build_with_tokio(sender, receiver))
-    }
-
-    async fn ws_transport(url: Url) -> Result<(Sender, Receiver), Error> {
-        WsTransportClientBuilder::default()
-            .build(url)
-            .await
-            .map_err(|_| Error::LightClient(LightClientError::Handshake))
-    }
 }
 
-#[cfg(all(feature = "jsonrpsee", feature = "web"))]
-mod jsonrpsee_helpers {
-    use crate::error::{Error, LightClientError};
-    pub use jsonrpsee::{
-        client_transport::web,
-        core::client::{Client, ClientBuilder},
-    };
+cfg_jsonrpsee_web! {
+    mod jsonrpsee_helpers {
+        use crate::error::{Error, LightClientError};
+        pub use jsonrpsee::{
+            client_transport::web,
+            core::client::{Client, ClientBuilder},
+        };
 
-    /// Build web RPC client from URL
-    pub async fn client(url: &str) -> Result<Client, Error> {
-        let (sender, receiver) = web::connect(url)
-            .await
-            .map_err(|_| Error::LightClient(LightClientError::Handshake))?;
+        /// Build web RPC client from URL
+        pub async fn client(url: &str) -> Result<Client, Error> {
+            let (sender, receiver) = web::connect(url)
+                .await
+                .map_err(|_| Error::LightClient(LightClientError::Handshake))?;
 
-        Ok(ClientBuilder::default()
-            .max_buffer_capacity_per_subscription(4096)
-            .build_with_wasm(sender, receiver))
+            Ok(ClientBuilder::default()
+                .max_buffer_capacity_per_subscription(4096)
+                .build_with_wasm(sender, receiver))
+        }
     }
 }

subxt/src/client/mod.rs

@@ -11,15 +11,15 @@
 mod offline_client;
 mod online_client;
 
-#[cfg(feature = "unstable-light-client")]
-mod light_client;
+crate::macros::cfg_unstable_light_client! {
+    mod light_client;
+
+    pub use light_client::{
+        LightClient, LightClientBuilder, LightClientError, RawLightClient, RawLightClientBuilder,
+    };
+}
 
 pub use offline_client::{OfflineClient, OfflineClientT};
 pub use online_client::{
     ClientRuntimeUpdater, OnlineClient, OnlineClientT, RuntimeUpdaterStream, Update, UpgradeError,
 };
-
-#[cfg(feature = "unstable-light-client")]
-pub use light_client::{
-    LightClient, LightClientBuilder, LightClientError, RawLightClient, RawLightClientBuilder,
-};

subxt/src/client/online_client.rs

@@ -56,6 +56,7 @@ impl<T: Config> std::fmt::Debug for OnlineClient<T> {
 
 // The default constructors assume Jsonrpsee.
 #[cfg(feature = "jsonrpsee")]
+#[cfg_attr(docsrs, doc(cfg(feature = "jsonrpsee")))]
 impl<T: Config> OnlineClient<T> {
     /// Construct a new [`OnlineClient`] using default settings which
     /// point to a locally running node on `ws://127.0.0.1:9944`.

subxt/src/config/mod.rs

@@ -15,6 +15,7 @@ pub mod polkadot;
 pub mod signed_extensions;
 pub mod substrate;
 
+use crate::macros::cfg_substrate_compat;
 use codec::{Decode, Encode};
 use core::fmt::Debug;
 use scale_decode::DecodeAsType;
@@ -125,28 +126,29 @@ pub trait Header: Sized + Encode + Decode {
     }
 }
 
-/// implement subxt's Hasher and Header traits for some substrate structs
-#[cfg(feature = "substrate-compat")]
-mod substrate_impls {
-    use super::*;
+cfg_substrate_compat! {
+    /// implement subxt's Hasher and Header traits for some substrate structs
+    mod substrate_impls {
+        use super::*;
 
-    impl<T: sp_runtime::traits::Header> Header for T
-    where
-        <T as sp_runtime::traits::Header>::Number: Into<u64>,
-    {
-        type Number = T::Number;
-        type Hasher = T::Hashing;
+        impl<T: sp_runtime::traits::Header> Header for T
+        where
+            <T as sp_runtime::traits::Header>::Number: Into<u64>,
+        {
+            type Number = T::Number;
+            type Hasher = T::Hashing;
 
-        fn number(&self) -> Self::Number {
-            *self.number()
+            fn number(&self) -> Self::Number {
+                *self.number()
+            }
         }
-    }
 
-    impl<T: sp_runtime::traits::Hash> Hasher for T {
-        type Output = T::Output;
+        impl<T: sp_runtime::traits::Hash> Hasher for T {
+            type Output = T::Output;
 
-        fn hash(s: &[u8]) -> Self::Output {
-            <T as sp_runtime::traits::Hash>::hash(s)
+            fn hash(s: &[u8]) -> Self::Output {
+                <T as sp_runtime::traits::Hash>::hash(s)
+            }
         }
     }
 }

subxt/src/error/mod.rs

@@ -8,8 +8,9 @@ mod dispatch_error;
 
 use core::fmt::Debug;
 
-#[cfg(feature = "unstable-light-client")]
-pub use crate::client::LightClientError;
+crate::macros::cfg_unstable_light_client! {
+    pub use crate::client::LightClientError;
+}
 
 // Re-export dispatch error types:
 pub use dispatch_error::{
@@ -73,6 +74,7 @@ pub enum Error {
     Unknown(Vec<u8>),
     /// Light client error.
     #[cfg(feature = "unstable-light-client")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-light-client")))]
     #[error("An error occurred but it could not be decoded: {0}")]
     LightClient(#[from] LightClientError),
     /// Other error.

subxt/src/lib.rs

@@ -10,6 +10,8 @@
 //!
 //! Take a look at [the Subxt guide](book) to learn more about how to use Subxt.
 
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 #[cfg(any(
     all(feature = "web", feature = "native"),
     not(any(feature = "web", feature = "native"))
@@ -55,6 +57,10 @@ pub mod storage;
 pub mod tx;
 pub mod utils;
 
+// Internal helper macros
+#[macro_use]
+mod macros;
+
 // Expose a few of the most common types at root,
 // but leave most types behind their respective modules.
 pub use crate::{
@@ -73,10 +79,11 @@ pub mod ext {
     pub use scale_decode;
     pub use scale_encode;
     pub use scale_value;
-    #[cfg(feature = "substrate-compat")]
-    pub use sp_core;
-    #[cfg(feature = "substrate-compat")]
-    pub use sp_runtime;
+
+    cfg_substrate_compat! {
+        pub use sp_runtime;
+        pub use sp_core;
+    }
 }
 
 /// Generate a strongly typed API for interacting with a Substrate runtime from its metadata.

subxt/src/macros.rs

@@ -0,0 +1,59 @@
+// Copyright 2019-2023 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+macro_rules! cfg_feature {
+	($feature:literal, $($item:item)*) => {
+		$(
+			#[cfg(feature = $feature)]
+			#[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
+			$item
+		)*
+	}
+}
+
+macro_rules! cfg_substrate_compat {
+	($($item:item)*) => {
+		crate::macros::cfg_feature!("substrate-compat", $($item)*);
+	};
+}
+
+macro_rules! cfg_unstable_light_client {
+	($($item:item)*) => {
+		crate::macros::cfg_feature!("unstable-light-client", $($item)*);
+	};
+}
+
+macro_rules! cfg_jsonrpsee {
+	($($item:item)*) => {
+		crate::macros::cfg_feature!("jsonrpsee", $($item)*);
+	};
+}
+
+#[allow(unused)]
+macro_rules! cfg_jsonrpsee_native {
+	($($item:item)*) => {
+		$(
+			#[cfg(all(feature = "jsonrpsee", feature = "native"))]
+			#[cfg_attr(docsrs, doc(cfg(all(feature = "jsonrpsee", feature = "native"))))]
+			$item
+		)*
+	}
+}
+
+#[allow(unused)]
+macro_rules! cfg_jsonrpsee_web {
+	($($item:item)*) => {
+		$(
+			#[cfg(all(feature = "jsonrpsee", feature = "web"))]
+			#[cfg_attr(docsrs, doc(cfg(all(feature = "jsonrpsee", feature = "web"))))]
+			$item
+		)*
+	}
+}
+
+pub(crate) use {cfg_feature, cfg_jsonrpsee, cfg_substrate_compat, cfg_unstable_light_client};
+
+// Only used by light-client.
+#[allow(unused)]
+pub(crate) use {cfg_jsonrpsee_native, cfg_jsonrpsee_web};

subxt/src/tx/mod.rs

@@ -9,6 +9,8 @@
 //! additional and signed extra parameters are used when constructing an extrinsic, and is a part
 //! of the chain configuration (see [`crate::config::Config`]).
 
+use crate::macros::cfg_substrate_compat;
+
 mod signer;
 mod tx_client;
 mod tx_payload;
@@ -16,8 +18,9 @@ mod tx_progress;
 
 // The PairSigner impl currently relies on Substrate bits and pieces, so make it an optional
 // feature if we want to avoid needing sp_core and sp_runtime.
-#[cfg(feature = "substrate-compat")]
-pub use self::signer::PairSigner;
+cfg_substrate_compat! {
+    pub use self::signer::PairSigner;
+}
 
 pub use self::{
     signer::Signer,

subxt/src/tx/signer.rs

@@ -5,6 +5,7 @@
 //! A library to **sub**mit e**xt**rinsics to a
 //! [substrate](https://github.com/paritytech/substrate) node via RPC.
 
+use crate::macros::cfg_substrate_compat;
 use crate::Config;
 
 /// Signing transactions requires a [`Signer`]. This is responsible for
@@ -24,8 +25,9 @@ pub trait Signer<T: Config> {
     fn sign(&self, signer_payload: &[u8]) -> T::Signature;
 }
 
-#[cfg(feature = "substrate-compat")]
-pub use pair_signer::PairSigner;
+cfg_substrate_compat! {
+    pub use pair_signer::PairSigner;
+}
 
 // A signer suitable for substrate based chains. This provides compatibility with Substrate
 // packages like sp_keyring and such, and so relies on sp_core and sp_runtime to be included.