From c27cd06a11ae575f5f6d44cbb51b837e4d51da05 Mon Sep 17 00:00:00 2001 From: nickelc Date: Thu, 18 Feb 2021 01:48:08 +0100 Subject: [PATCH] Use `doc_cfg` to show feature requirements (#1134) * Use `doc_cfg` to show feature requirements * Apply suggestions from code review --- Cargo.toml | 1 + src/async_impl/client.rs | 12 ++++++++++++ src/async_impl/request.rs | 2 ++ src/async_impl/response.rs | 3 +++ src/blocking/client.rs | 12 ++++++++++++ src/blocking/request.rs | 2 ++ src/blocking/response.rs | 2 ++ src/lib.rs | 1 + src/wasm/request.rs | 2 ++ src/wasm/response.rs | 1 + 10 files changed, 38 insertions(+) diff --git a/Cargo.toml b/Cargo.toml index cce2a28..cd6ebd4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,6 +14,7 @@ autotests = true [package.metadata.docs.rs] all-features = true +rustdoc-args = ["--cfg", "docsrs"] targets = ["x86_64-unknown-linux-gnu", "wasm32-unknown-unknown"] [package.metadata.playground] diff --git a/src/async_impl/client.rs b/src/async_impl/client.rs index 16ee45a..f286f64 100644 --- a/src/async_impl/client.rs +++ b/src/async_impl/client.rs @@ -461,6 +461,7 @@ impl ClientBuilder { /// /// This requires the optional `cookies` feature to be enabled. #[cfg(feature = "cookies")] + #[cfg_attr(docsrs, doc(cfg(feature = "cookies")))] pub fn cookie_store(mut self, enable: bool) -> ClientBuilder { self.config.cookie_store = if enable { Some(cookie::CookieStore::default()) @@ -487,6 +488,7 @@ impl ClientBuilder { /// /// This requires the optional `gzip` feature to be enabled #[cfg(feature = "gzip")] + #[cfg_attr(docsrs, doc(cfg(feature = "gzip")))] pub fn gzip(mut self, enable: bool) -> ClientBuilder { self.config.accepts.gzip = enable; self @@ -509,6 +511,7 @@ impl ClientBuilder { /// /// This requires the optional `brotli` feature to be enabled #[cfg(feature = "brotli")] + #[cfg_attr(docsrs, doc(cfg(feature = "brotli")))] pub fn brotli(mut self, enable: bool) -> ClientBuilder { self.config.accepts.brotli = enable; self @@ -729,6 +732,7 @@ impl ClientBuilder { /// This requires the optional `default-tls`, `native-tls`, or `rustls-tls(-...)` /// feature to be enabled. #[cfg(feature = "__tls")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "default-tls", feature = "native-tls", feature = "rustls-tls"))))] pub fn add_root_certificate(mut self, cert: Certificate) -> ClientBuilder { self.config.root_certs.push(cert); self @@ -743,6 +747,7 @@ impl ClientBuilder { /// This requires the optional `default-tls`, `native-tls`, or `rustls-tls(-...)` /// feature to be enabled. #[cfg(feature = "__tls")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "default-tls", feature = "native-tls", feature = "rustls-tls"))))] pub fn tls_built_in_root_certs( mut self, tls_built_in_root_certs: bool, @@ -758,6 +763,7 @@ impl ClientBuilder { /// This requires the optional `native-tls` or `rustls-tls(-...)` feature to be /// enabled. #[cfg(any(feature = "native-tls", feature = "__rustls"))] + #[cfg_attr(docsrs, doc(cfg(any(feature = "native-tls", feature = "rustls-tls"))))] pub fn identity(mut self, identity: Identity) -> ClientBuilder { self.config.identity = Some(identity); self @@ -778,6 +784,7 @@ impl ClientBuilder { /// /// This requires the optional `native-tls` feature to be enabled. #[cfg(feature = "native-tls")] + #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))] pub fn danger_accept_invalid_hostnames( mut self, accept_invalid_hostname: bool, @@ -803,6 +810,7 @@ impl ClientBuilder { /// This requires the optional `default-tls`, `native-tls`, or `rustls-tls(-...)` /// feature to be enabled. #[cfg(feature = "__tls")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "default-tls", feature = "native-tls", feature = "rustls-tls"))))] pub fn danger_accept_invalid_certs(mut self, accept_invalid_certs: bool) -> ClientBuilder { self.config.certs_verification = !accept_invalid_certs; self @@ -817,6 +825,7 @@ impl ClientBuilder { /// /// This requires the optional `native-tls` feature to be enabled. #[cfg(feature = "native-tls")] + #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))] pub fn use_native_tls(mut self) -> ClientBuilder { self.config.tls = TlsBackend::Default; self @@ -831,6 +840,7 @@ impl ClientBuilder { /// /// This requires the optional `rustls-tls(-...)` feature to be enabled. #[cfg(feature = "__rustls")] + #[cfg_attr(docsrs, doc(cfg(feature = "rustls-tls")))] pub fn use_rustls_tls(mut self) -> ClientBuilder { self.config.tls = TlsBackend::Rustls; self @@ -858,6 +868,7 @@ impl ClientBuilder { feature = "native-tls", feature = "__rustls", ))] + #[cfg_attr(docsrs, doc(cfg(any(feature = "native-tls", feature = "rustls-tls"))))] pub fn use_preconfigured_tls(mut self, tls: impl Any) -> ClientBuilder { let mut tls = Some(tls); #[cfg(feature = "native-tls")] @@ -893,6 +904,7 @@ impl ClientBuilder { /// /// This requires the optional `trust-dns` feature to be enabled #[cfg(feature = "trust-dns")] + #[cfg_attr(docsrs, doc(cfg(feature = "trust-dns")))] pub fn trust_dns(mut self, enable: bool) -> ClientBuilder { self.config.trust_dns = enable; self diff --git a/src/async_impl/request.rs b/src/async_impl/request.rs index fdb542b..2b01954 100644 --- a/src/async_impl/request.rs +++ b/src/async_impl/request.rs @@ -264,6 +264,7 @@ impl RequestBuilder { /// # } /// ``` #[cfg(feature = "multipart")] + #[cfg_attr(docsrs, doc(cfg(feature = "multipart")))] pub fn multipart(self, mut multipart: multipart::Form) -> RequestBuilder { let mut builder = self.header( CONTENT_TYPE, @@ -353,6 +354,7 @@ impl RequestBuilder { /// Serialization can fail if `T`'s implementation of `Serialize` decides to /// fail, or if `T` contains a map with non-string keys. #[cfg(feature = "json")] + #[cfg_attr(docsrs, doc(cfg(feature = "json")))] pub fn json(mut self, json: &T) -> RequestBuilder { let mut error = None; if let Ok(ref mut req) = self.request { diff --git a/src/async_impl/response.rs b/src/async_impl/response.rs index 2035f01..7d98840 100644 --- a/src/async_impl/response.rs +++ b/src/async_impl/response.rs @@ -103,6 +103,7 @@ impl Response { /// /// This requires the optional `cookies` feature to be enabled. #[cfg(feature = "cookies")] + #[cfg_attr(docsrs, doc(cfg(feature = "cookies")))] pub fn cookies<'a>(&'a self) -> impl Iterator> + 'a { cookie::extract_response_cookies(&self.headers).filter_map(Result::ok) } @@ -236,6 +237,7 @@ impl Response { /// /// [`serde_json::from_reader`]: https://docs.serde.rs/serde_json/fn.from_reader.html #[cfg(feature = "json")] + #[cfg_attr(docsrs, doc(cfg(feature = "json")))] pub async fn json(self) -> crate::Result { let full = self.bytes().await?; @@ -308,6 +310,7 @@ impl Response { /// /// This requires the optional `stream` feature to be enabled. #[cfg(feature = "stream")] + #[cfg_attr(docsrs, doc(cfg(feature = "stream")))] pub fn bytes_stream(self) -> impl futures_core::Stream> { self.body } diff --git a/src/blocking/client.rs b/src/blocking/client.rs index c2f0e4b..ed1019a 100644 --- a/src/blocking/client.rs +++ b/src/blocking/client.rs @@ -194,6 +194,7 @@ impl ClientBuilder { /// /// This requires the optional `cookies` feature to be enabled. #[cfg(feature = "cookies")] + #[cfg_attr(docsrs, doc(cfg(feature = "cookies")))] pub fn cookie_store(self, enable: bool) -> ClientBuilder { self.with_inner(|inner| inner.cookie_store(enable)) } @@ -215,6 +216,7 @@ impl ClientBuilder { /// /// This requires the optional `gzip` feature to be enabled #[cfg(feature = "gzip")] + #[cfg_attr(docsrs, doc(cfg(feature = "gzip")))] pub fn gzip(self, enable: bool) -> ClientBuilder { self.with_inner(|inner| inner.gzip(enable)) } @@ -236,6 +238,7 @@ impl ClientBuilder { /// /// This requires the optional `brotli` feature to be enabled #[cfg(feature = "brotli")] + #[cfg_attr(docsrs, doc(cfg(feature = "brotli")))] pub fn brotli(self, enable: bool) -> ClientBuilder { self.with_inner(|inner| inner.brotli(enable)) } /// Disable auto response body gzip decompression. @@ -442,6 +445,7 @@ impl ClientBuilder { /// This requires the optional `default-tls`, `native-tls`, or `rustls-tls(-...)` /// feature to be enabled. #[cfg(feature = "__tls")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "default-tls", feature = "native-tls", feature = "rustls-tls"))))] pub fn add_root_certificate(self, cert: Certificate) -> ClientBuilder { self.with_inner(move |inner| inner.add_root_certificate(cert)) } @@ -455,6 +459,7 @@ impl ClientBuilder { /// This requires the optional `default-tls`, `native-tls`, or `rustls-tls(-...)` /// feature to be enabled. #[cfg(feature = "__tls")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "default-tls", feature = "native-tls", feature = "rustls-tls"))))] pub fn tls_built_in_root_certs( self, tls_built_in_root_certs: bool, @@ -469,6 +474,7 @@ impl ClientBuilder { /// This requires the optional `native-tls` or `rustls-tls(-...)` feature to be /// enabled. #[cfg(any(feature = "native-tls", feature = "__rustls"))] + #[cfg_attr(docsrs, doc(cfg(any(feature = "native-tls", feature = "rustls-tls"))))] pub fn identity(self, identity: Identity) -> ClientBuilder { self.with_inner(move |inner| inner.identity(identity)) } @@ -488,6 +494,7 @@ impl ClientBuilder { /// /// This requires the optional `native-tls` feature to be enabled. #[cfg(feature = "native-tls")] + #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))] pub fn danger_accept_invalid_hostnames(self, accept_invalid_hostname: bool) -> ClientBuilder { self.with_inner(|inner| inner.danger_accept_invalid_hostnames(accept_invalid_hostname)) } @@ -504,6 +511,7 @@ impl ClientBuilder { /// introduces significant vulnerabilities, and should only be used /// as a last resort. #[cfg(feature = "__tls")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "default-tls", feature = "native-tls", feature = "rustls-tls"))))] pub fn danger_accept_invalid_certs(self, accept_invalid_certs: bool) -> ClientBuilder { self.with_inner(|inner| inner.danger_accept_invalid_certs(accept_invalid_certs)) } @@ -517,6 +525,7 @@ impl ClientBuilder { /// /// This requires the optional `native-tls` feature to be enabled. #[cfg(feature = "native-tls")] + #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))] pub fn use_native_tls(self) -> ClientBuilder { self.with_inner(move |inner| inner.use_native_tls()) } @@ -530,6 +539,7 @@ impl ClientBuilder { /// /// This requires the optional `rustls-tls(-...)` feature to be enabled. #[cfg(feature = "__rustls")] + #[cfg_attr(docsrs, doc(cfg(feature = "rustls-tls")))] pub fn use_rustls_tls(self) -> ClientBuilder { self.with_inner(move |inner| inner.use_rustls_tls()) } @@ -556,6 +566,7 @@ impl ClientBuilder { feature = "native-tls", feature = "__rustls", ))] + #[cfg_attr(docsrs, doc(cfg(any(feature = "native-tls", feature = "rustls-tls"))))] pub fn use_preconfigured_tls(self, tls: impl Any) -> ClientBuilder { self.with_inner(move |inner| inner.use_preconfigured_tls(tls)) } @@ -568,6 +579,7 @@ impl ClientBuilder { /// /// This requires the optional `trust-dns` feature to be enabled #[cfg(feature = "trust-dns")] + #[cfg_attr(docsrs, doc(cfg(feature = "trust-dns")))] pub fn trust_dns(self, enable: bool) -> ClientBuilder { self.with_inner(|inner| inner.trust_dns(enable)) } diff --git a/src/blocking/request.rs b/src/blocking/request.rs index 72a1426..11ad687 100644 --- a/src/blocking/request.rs +++ b/src/blocking/request.rs @@ -472,6 +472,7 @@ impl RequestBuilder { /// Serialization can fail if `T`'s implementation of `Serialize` decides to /// fail, or if `T` contains a map with non-string keys. #[cfg(feature = "json")] + #[cfg_attr(docsrs, doc(cfg(feature = "json")))] pub fn json(mut self, json: &T) -> RequestBuilder { let mut error = None; if let Ok(ref mut req) = self.request { @@ -510,6 +511,7 @@ impl RequestBuilder { /// /// See [`multipart`](multipart/) for more examples. #[cfg(feature = "multipart")] + #[cfg_attr(docsrs, doc(cfg(feature = "multipart")))] pub fn multipart(self, mut multipart: multipart::Form) -> RequestBuilder { let mut builder = self.header( CONTENT_TYPE, diff --git a/src/blocking/response.rs b/src/blocking/response.rs index c97f741..96b0f8f 100644 --- a/src/blocking/response.rs +++ b/src/blocking/response.rs @@ -136,6 +136,7 @@ impl Response { /// /// This requires the optional `cookies` feature to be enabled. #[cfg(feature = "cookies")] + #[cfg_attr(docsrs, doc(cfg(feature = "cookies")))] pub fn cookies<'a>(&'a self) -> impl Iterator> + 'a { cookie::extract_response_cookies(self.headers()).filter_map(Result::ok) } @@ -225,6 +226,7 @@ impl Response { /// /// [`serde_json::from_reader`]: https://docs.serde.rs/serde_json/fn.from_reader.html #[cfg(feature = "json")] + #[cfg_attr(docsrs, doc(cfg(feature = "json")))] pub fn json(self) -> crate::Result { wait::timeout(self.inner.json(), self.timeout).map_err(|e| match e { wait::Waited::TimedOut(e) => crate::error::decode(e), diff --git a/src/lib.rs b/src/lib.rs index beb3f63..aacbb92 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,6 @@ #![deny(missing_docs)] #![deny(missing_debug_implementations)] +#![cfg_attr(docsrs, feature(doc_cfg))] #![cfg_attr(test, deny(warnings))] #![doc(html_root_url = "https://docs.rs/reqwest/0.11.0")] diff --git a/src/wasm/request.rs b/src/wasm/request.rs index c6828e1..b1359f3 100644 --- a/src/wasm/request.rs +++ b/src/wasm/request.rs @@ -155,6 +155,7 @@ impl RequestBuilder { } #[cfg(feature = "json")] + #[cfg_attr(docsrs, doc(cfg(feature = "json")))] /// Set the request json pub fn json(mut self, json: &T) -> RequestBuilder { let mut error = None; @@ -194,6 +195,7 @@ impl RequestBuilder { /// TODO #[cfg(feature = "multipart")] + #[cfg_attr(docsrs, doc(cfg(feature = "multipart")))] pub fn multipart(mut self, multipart: super::multipart::Form) -> RequestBuilder { if let Ok(ref mut req) = self.request { *req.body_mut() = Some(Body::from_form(multipart)) diff --git a/src/wasm/response.rs b/src/wasm/response.rs index a319dc7..6bf2f14 100644 --- a/src/wasm/response.rs +++ b/src/wasm/response.rs @@ -77,6 +77,7 @@ impl Response { /// Try to deserialize the response body as JSON. #[cfg(feature = "json")] + #[cfg_attr(docsrs, doc(cfg(feature = "json")))] pub async fn json(self) -> crate::Result { let full = self.bytes().await?;