Add doc_cfg attributes (#483)

* docs(Cargo.toml): Add `cfg(docsrs)` to `rustdoc` args

* docs(all): Enable doc_cfg crate feature

* docs(transport): Add doc_cfg to Transport traits

* docs(all): Add doc_cfg to public modules

* docs(transport-async): Add doc_cfg to Tokio02Connector

* docs(transport-smtp): Add doc_cfg to Smtp Error

* docs(transport-smtp): Add doc_cfg to TlsParameters

Cargo.toml

@@ -90,6 +90,7 @@ tokio02-rustls-tls = ["tokio02", "rustls-tls", "tokio02_rustls"]
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
 
 [[example]]
 name = "smtp"

src/lib.rs

@@ -36,10 +36,12 @@
     unused_import_braces,
     rust_2018_idioms
 )]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 pub mod address;
 pub mod error;
 #[cfg(feature = "builder")]
+#[cfg_attr(docsrs, doc(cfg(feature = "builder")))]
 pub mod message;
 pub mod transport;
 
@@ -200,6 +202,7 @@ pub trait Transport {
 
     /// Sends the email
     #[cfg(feature = "builder")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "builder")))]
     fn send(&self, message: &Message) -> Result<Self::Ok, Self::Error> {
         let raw = message.formatted();
         self.send_raw(message.envelope(), &raw)
@@ -210,6 +213,7 @@ pub trait Transport {
 
 /// async-std 1.x based Transport method for emails
 #[cfg(feature = "async-std1")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async-std1")))]
 #[async_trait]
 pub trait AsyncStd1Transport {
     /// Response produced by the Transport
@@ -219,6 +223,7 @@ pub trait AsyncStd1Transport {
 
     /// Sends the email
     #[cfg(feature = "builder")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "builder")))]
     // TODO take &Message
     async fn send(&self, message: Message) -> Result<Self::Ok, Self::Error> {
         let raw = message.formatted();
@@ -231,6 +236,7 @@ pub trait AsyncStd1Transport {
 
 /// tokio 0.2.x based Transport method for emails
 #[cfg(feature = "tokio02")]
+#[cfg_attr(docsrs, doc(cfg(feature = "tokio02")))]
 #[async_trait]
 pub trait Tokio02Transport {
     /// Response produced by the Transport
@@ -240,6 +246,7 @@ pub trait Tokio02Transport {
 
     /// Sends the email
     #[cfg(feature = "builder")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "builder")))]
     // TODO take &Message
     async fn send(&self, message: Message) -> Result<Self::Ok, Self::Error> {
         let raw = message.formatted();

src/transport/mod.rs

@@ -17,9 +17,12 @@
 //!   logs.
 
 #[cfg(feature = "file-transport")]
+#[cfg_attr(docsrs, doc(cfg(feature = "file-transport")))]
 pub mod file;
 #[cfg(feature = "sendmail-transport")]
+#[cfg_attr(docsrs, doc(cfg(feature = "sendmail-transport")))]
 pub mod sendmail;
 #[cfg(feature = "smtp-transport")]
+#[cfg_attr(docsrs, doc(cfg(feature = "smtp-transport")))]
 pub mod smtp;
 pub mod stub;

src/transport/smtp/async_transport.rs

@@ -195,6 +195,7 @@ pub trait AsyncSmtpConnector: Default + private::Sealed {
 
 #[derive(Debug, Copy, Clone, Default)]
 #[cfg(feature = "tokio02")]
+#[cfg_attr(docsrs, doc(cfg(feature = "tokio02")))]
 pub struct Tokio02Connector;
 
 #[async_trait]

src/transport/smtp/client/tls.rs

@@ -84,6 +84,7 @@ impl TlsParametersBuilder {
     ///
     /// Hostname verification can only be disabled with the `native-tls` TLS backend.
     #[cfg(feature = "native-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
     pub fn dangerous_accept_invalid_hostnames(
         &mut self,
         accept_invalid_hostnames: bool,
@@ -116,6 +117,7 @@ impl TlsParametersBuilder {
     /// Creates a new `TlsParameters` using native-tls or rustls
     /// depending on which one is available
     #[cfg(any(feature = "native-tls", feature = "rustls-tls"))]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "native-tls", feature = "rustls-tls"))))]
     pub fn build(self) -> Result<TlsParameters, Error> {
         #[cfg(feature = "native-tls")]
         return self.build_native();
@@ -135,6 +137,7 @@ impl TlsParametersBuilder {
 
     /// Creates a new `TlsParameters` using native-tls with the provided configuration
     #[cfg(feature = "native-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
     pub fn build_native(self) -> Result<TlsParameters, Error> {
         let mut tls_builder = TlsConnector::builder();
 
@@ -154,6 +157,7 @@ impl TlsParametersBuilder {
 
     /// Creates a new `TlsParameters` using rustls with the provided configuration
     #[cfg(feature = "rustls-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "rustls-tls")))]
     pub fn build_rustls(self) -> Result<TlsParameters, Error> {
         use webpki_roots::TLS_SERVER_ROOTS;
 
@@ -191,6 +195,7 @@ impl TlsParameters {
     /// Creates a new `TlsParameters` using native-tls or rustls
     /// depending on which one is available
     #[cfg(any(feature = "native-tls", feature = "rustls-tls"))]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "native-tls", feature = "rustls-tls"))))]
     pub fn new(domain: String) -> Result<Self, Error> {
         TlsParametersBuilder::new(domain).build()
     }
@@ -201,12 +206,14 @@ impl TlsParameters {
 
     /// Creates a new `TlsParameters` using native-tls
     #[cfg(feature = "native-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
     pub fn new_native(domain: String) -> Result<Self, Error> {
         TlsParametersBuilder::new(domain).build_native()
     }
 
     /// Creates a new `TlsParameters` using rustls
     #[cfg(feature = "rustls-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "rustls-tls")))]
     pub fn new_rustls(domain: String) -> Result<Self, Error> {
         TlsParametersBuilder::new(domain).build_rustls()
     }

src/transport/smtp/error.rs

@@ -35,15 +35,19 @@ pub enum Error {
     Io(io::Error),
     /// TLS error
     #[cfg(feature = "native-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
     Tls(native_tls::Error),
     /// Parsing error
     Parsing(nom::error::ErrorKind),
     /// Invalid hostname
     #[cfg(feature = "rustls-tls")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "rustls-tls")))]
     InvalidDNSName(webpki::InvalidDNSNameError),
     #[cfg(any(feature = "native-tls", feature = "rustls-tls"))]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "native-tls", feature = "rustls-tls"))))]
     InvalidCertificate,
     #[cfg(feature = "r2d2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "r2d2")))]
     Pool(r2d2::Error),
 }
 

src/transport/smtp/mod.rs

@@ -182,6 +182,7 @@ pub mod commands;
 mod error;
 pub mod extension;
 #[cfg(feature = "r2d2")]
+#[cfg_attr(docsrs, doc(cfg(feature = "r2d2")))]
 pub mod pool;
 pub mod response;
 mod transport;