From fd1425666d0905871fba70e713a37f8a5339dbdd Mon Sep 17 00:00:00 2001
From: Paolo Barbolini <paolo.barbolini@m4ss.net>
Date: Mon, 23 Dec 2024 16:43:39 +0100
Subject: [PATCH] docs: warn against manually configuring port and tls configs
 (#1014)

---
 src/transport/smtp/async_transport.rs | 30 ++++++++++++++++++++++++++-
 src/transport/smtp/transport.rs       | 22 ++++++++++++++++++++
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/src/transport/smtp/async_transport.rs b/src/transport/smtp/async_transport.rs
index 8898f00..55e4a25 100644
--- a/src/transport/smtp/async_transport.rs
+++ b/src/transport/smtp/async_transport.rs
@@ -12,6 +12,12 @@ use async_trait::async_trait;
 use super::pool::async_impl::Pool;
 #[cfg(feature = "pool")]
 use super::PoolConfig;
+#[cfg(any(
+    feature = "tokio1-native-tls",
+    feature = "tokio1-rustls-tls",
+    feature = "async-std1-rustls-tls"
+))]
+use super::Tls;
 use super::{
     client::AsyncSmtpConnection, ClientId, Credentials, Error, Mechanism, Response, SmtpInfo,
 };
@@ -336,6 +342,17 @@ impl AsyncSmtpTransportBuilder {
     }
 
     /// Set the port to use
+    ///
+    /// # ⚠️⚠️⚠️ You probably don't need to call this method ⚠️⚠️⚠️
+    ///
+    /// lettre usually picks the correct `port` when building
+    /// [`AsyncSmtpTransport`] using [`AsyncSmtpTransport::relay`] or
+    /// [`AsyncSmtpTransport::starttls_relay`].
+    ///
+    /// # Errors
+    ///
+    /// Using the incorrect `port` and [`Self::tls`] combination may
+    /// lead to hard to debug IO errors coming from the TLS library.
     pub fn port(mut self, port: u16) -> Self {
         self.info.port = port;
         self
@@ -348,6 +365,17 @@ impl AsyncSmtpTransportBuilder {
     }
 
     /// Set the TLS settings to use
+    ///
+    /// # ⚠️⚠️⚠️ You probably don't need to call this method ⚠️⚠️⚠️
+    ///
+    /// By default lettre chooses the correct `tls` configuration when
+    /// building [`AsyncSmtpTransport`] using [`AsyncSmtpTransport::relay`] or
+    /// [`AsyncSmtpTransport::starttls_relay`].
+    ///
+    /// # Errors
+    ///
+    /// Using the incorrect [`Tls`] and [`Self::port`] combination may
+    /// lead to hard to debug IO errors coming from the TLS library.
     #[cfg(any(
         feature = "tokio1-native-tls",
         feature = "tokio1-rustls-tls",
@@ -361,7 +389,7 @@ impl AsyncSmtpTransportBuilder {
             feature = "async-std1-rustls-tls"
         )))
     )]
-    pub fn tls(mut self, tls: super::Tls) -> Self {
+    pub fn tls(mut self, tls: Tls) -> Self {
         self.info.tls = tls;
         self
     }
diff --git a/src/transport/smtp/transport.rs b/src/transport/smtp/transport.rs
index 3bbc8b1..2733e96 100644
--- a/src/transport/smtp/transport.rs
+++ b/src/transport/smtp/transport.rs
@@ -265,12 +265,34 @@ impl SmtpTransportBuilder {
     }
 
     /// Set the port to use
+    ///
+    /// # ⚠️⚠️⚠️ You probably don't need to call this method ⚠️⚠️⚠️
+    ///
+    /// lettre usually picks the correct `port` when building
+    /// [`SmtpTransport`] using [`SmtpTransport::relay`] or
+    /// [`SmtpTransport::starttls_relay`].
+    ///
+    /// # Errors
+    ///
+    /// Using the incorrect `port` and [`Self::tls`] combination may
+    /// lead to hard to debug IO errors coming from the TLS library.
     pub fn port(mut self, port: u16) -> Self {
         self.info.port = port;
         self
     }
 
     /// Set the TLS settings to use
+    ///
+    /// # ⚠️⚠️⚠️ You probably don't need to call this method ⚠️⚠️⚠️
+    ///
+    /// By default lettre chooses the correct `tls` configuration when
+    /// building [`SmtpTransport`] using [`SmtpTransport::relay`] or
+    /// [`SmtpTransport::starttls_relay`].
+    ///
+    /// # Errors
+    ///
+    /// Using the wrong [`Tls`] and [`Self::port`] combination may
+    /// lead to hard to debug IO errors coming from the TLS library.
     #[cfg(any(feature = "native-tls", feature = "rustls-tls", feature = "boring-tls"))]
     #[cfg_attr(
         docsrs,