From 62725af00a11fa1f9ab368dcf5fdee32851621db Mon Sep 17 00:00:00 2001
From: Paolo Barbolini <paolo@paolo565.org>
Date: Mon, 18 Jul 2022 09:40:46 +0200
Subject: [PATCH] Improve `TlsVersion` docs and remember to re-export it (#800)

---
 src/transport/smtp/client/mod.rs |  2 ++
 src/transport/smtp/client/tls.rs | 33 ++++++++++++++++++++++++++++----
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/src/transport/smtp/client/mod.rs b/src/transport/smtp/client/mod.rs
index 9aa9815..557d2e6 100644
--- a/src/transport/smtp/client/mod.rs
+++ b/src/transport/smtp/client/mod.rs
@@ -32,6 +32,8 @@ pub use self::async_net::AsyncNetworkStream;
 use self::net::NetworkStream;
 #[cfg(any(feature = "native-tls", feature = "rustls-tls", feature = "boring-tls"))]
 pub(super) use self::tls::InnerTlsParameters;
+#[cfg(any(feature = "native-tls", feature = "rustls-tls", feature = "boring-tls"))]
+pub use self::tls::TlsVersion;
 pub use self::{
     connection::SmtpConnection,
     tls::{Certificate, Tls, TlsParameters, TlsParametersBuilder},
diff --git a/src/transport/smtp/client/tls.rs b/src/transport/smtp/client/tls.rs
index 6476ee2..1a871d6 100644
--- a/src/transport/smtp/client/tls.rs
+++ b/src/transport/smtp/client/tls.rs
@@ -12,20 +12,45 @@ use rustls::{
     ClientConfig, Error as TlsError, OwnedTrustAnchor, RootCertStore, ServerName,
 };
 
+#[cfg(any(feature = "native-tls", feature = "rustls-tls", feature = "boring-tls"))]
+use crate::transport::smtp::{error, Error};
+
 /// TLS protocol versions.
 #[derive(Debug, Copy, Clone)]
 #[non_exhaustive]
 #[cfg(any(feature = "native-tls", feature = "rustls-tls", feature = "boring-tls"))]
 pub enum TlsVersion {
+    /// TLS 1.0
+    ///
+    /// Should only be used when trying to support legacy
+    /// SMTP servers that haven't updated to
+    /// at least TLS 1.2 yet.
+    ///
+    /// Supported by `native-tls` and `boring-tls`.
     Tlsv10,
+    /// TLS 1.1
+    ///
+    /// Should only be used when trying to support legacy
+    /// SMTP servers that haven't updated to
+    /// at least TLS 1.2 yet.
+    ///
+    /// Supported by `native-tls` and `boring-tls`.
     Tlsv11,
+    /// TLS 1.2
+    ///
+    /// A good option for most SMTP servers.
+    ///
+    /// Supported by all TLS backends.
     Tlsv12,
+    /// TLS 1.3
+    ///
+    /// The most secure option, altough not supported by all SMTP servers.
+    ///
+    /// Altough it is technically supported by all TLS backends,
+    /// trying to set it for `native-tls` will give a runtime error.
     Tlsv13,
 }
 
-#[cfg(any(feature = "native-tls", feature = "rustls-tls", feature = "boring-tls"))]
-use crate::transport::smtp::{error, Error};
-
 /// How to apply TLS to a client connection
 #[derive(Clone)]
 #[allow(missing_copy_implementations)]
@@ -132,7 +157,7 @@ impl TlsParametersBuilder {
 
     /// Controls which minimum TLS version is allowed
     ///
-    /// Defaults to `Tlsv12`.
+    /// Defaults to [`Tlsv12`][TlsVersion::Tlsv12].
     #[cfg(any(feature = "native-tls", feature = "rustls-tls", feature = "boring-tls"))]
     pub fn set_min_tls_version(mut self, min_tls_version: TlsVersion) -> Self {
         self.min_tls_version = min_tls_version;