Improve documentation for SmtpTransport methods

src/transport/smtp/async_transport.rs

@@ -34,7 +34,10 @@ impl<C> AsyncSmtpTransport<C>
 where
     C: AsyncSmtpConnector,
 {
-    /// Simple and secure transport, should be used when possible.
+    /// Simple and secure transport, using TLS connections to comunicate with the SMTP server
+    ///
+    /// The right option for most SMTP servers.
+    ///
     /// Creates an encrypted transport over submissions port, using the provided domain
     /// to validate TLS certificates.
     #[cfg(any(feature = "tokio02-native-tls", feature = "tokio02-rustls-tls"))]
@@ -48,10 +51,17 @@ where
             .tls(Tls::Wrapper(tls_parameters)))
     }
 
-    /// Simple and secure transport, should be used when the server doesn't support wrapped TLS connections.
+    /// Simple an secure transport, using STARTTLS to obtain encrypted connections
-    /// Creates an encrypted transport over submissions port, by first connecting using an unencrypted
+    ///
-    /// connection and then upgrading it with STARTTLS, using the provided domain to validate TLS certificates.
+    /// Alternative to [`AsyncSmtpTransport::relay`](#method.relay), for SMTP servers
-    /// If the connection can't be upgraded it will fail connecting altogether.
+    /// that don't take SMTPS connections.
+    ///
+    /// Creates an encrypted transport over submissions port, by first connecting using
+    /// an unencrypted connection and then upgrading it with STARTTLS. The provided
+    /// domain is used to validate TLS certificates.
+    ///
+    /// An error is returned if the connection can't be upgraded. No credentials
+    /// or emails will be sent to the server, protecting from downgrade attacks.
     #[cfg(any(feature = "tokio02-native-tls", feature = "tokio02-rustls-tls"))]
     pub fn starttls_relay(relay: &str) -> Result<AsyncSmtpTransportBuilder, Error> {
         use super::{TlsParameters, SUBMISSION_PORT};
@@ -78,7 +88,9 @@ where
     /// * No TLS
     /// * Port 25
     ///
-    /// Consider using [`AsyncSmtpTransport::relay`] instead, if possible.
+    /// Consider using [`AsyncSmtpTransport::relay`](#method.relay) or
+    /// [`AsyncSmtpTransport::starttls_relay`](#method.starttls_relay) instead,
+    /// if possible.
     pub fn builder_dangerous<T: Into<String>>(server: T) -> AsyncSmtpTransportBuilder {
         let mut new = SmtpInfo::default();
         new.server = server.into();

src/transport/smtp/transport.rs

@@ -38,7 +38,10 @@ impl Transport for SmtpTransport {
 }
 
 impl SmtpTransport {
-    /// Simple and secure transport, should be used when possible.
+    /// Simple and secure transport, using TLS connections to comunicate with the SMTP server
+    ///
+    /// The right option for most SMTP servers.
+    ///
     /// Creates an encrypted transport over submissions port, using the provided domain
     /// to validate TLS certificates.
     #[cfg(any(feature = "native-tls", feature = "rustls-tls"))]
@@ -50,10 +53,17 @@ impl SmtpTransport {
             .tls(Tls::Wrapper(tls_parameters)))
     }
 
-    /// Simple and secure transport, should be used when the server doesn't support wrapped TLS connections.
+    /// Simple an secure transport, using STARTTLS to obtain encrypted connections
-    /// Creates an encrypted transport over submissions port, by first connecting using an unencrypted
+    ///
-    /// connection and then upgrading it with STARTTLS, using the provided domain to validate TLS certificates.
+    /// Alternative to [`SmtpTransport::relay`](#method.relay), for SMTP servers
-    /// If the connection can't be upgraded it will fail connecting altogether.
+    /// that don't take SMTPS connections.
+    ///
+    /// Creates an encrypted transport over submissions port, by first connecting using
+    /// an unencrypted connection and then upgrading it with STARTTLS. The provided
+    /// domain is used to validate TLS certificates.
+    ///
+    /// An error is returned if the connection can't be upgraded. No credentials
+    /// or emails will be sent to the server, protecting from downgrade attacks.
     #[cfg(any(feature = "native-tls", feature = "rustls-tls"))]
     pub fn starttls_relay(relay: &str) -> Result<SmtpTransportBuilder, Error> {
         let tls_parameters = TlsParameters::new(relay.into())?;
@@ -79,7 +89,9 @@ impl SmtpTransport {
     /// * A 60 seconds timeout for smtp commands
     /// * Port 25
     ///
-    /// Consider using [`SmtpTransport::relay`] instead, if possible.
+    /// Consider using [`SmtpTransport::relay`](#method.relay) or
+    /// [`SmtpTransport::starttls_relay`](#method.starttls_relay) instead,
+    /// if possible.
     pub fn builder_dangerous<T: Into<String>>(server: T) -> SmtpTransportBuilder {
         let mut new = SmtpInfo::default();
         new.server = server.into();