Add documentation to undocumented items (#793)

src/message/header/mod.rs

@@ -277,6 +277,7 @@ impl PartialEq<HeaderName> for &str {
     }
 }
 
+/// A safe for use header value
 #[derive(Debug, Clone, PartialEq)]
 pub struct HeaderValue {
     name: HeaderName,
@@ -285,6 +286,12 @@ pub struct HeaderValue {
 }
 
 impl HeaderValue {
+    /// Construct a new `HeaderValue` and encode it
+    ///
+    /// Takes the header `name` and the `raw_value` and encodes
+    /// it via `RFC2047` and line folds it.
+    ///
+    /// [`RFC2047`]: https://datatracker.ietf.org/doc/html/rfc2047
     pub fn new(name: HeaderName, raw_value: String) -> Self {
         let mut encoded_value = String::with_capacity(raw_value.len());
         HeaderValueEncoder::encode(&name, &raw_value, &mut encoded_value).unwrap();
@@ -296,6 +303,14 @@ impl HeaderValue {
         }
     }
 
+    /// Construct a new `HeaderValue` using a pre-encoded header value
+    ///
+    /// This method is _extremely_ dangerous as it opens up
+    /// the encoder to header injection attacks, but is sometimes
+    /// acceptable for use if `encoded_value` contains only ascii
+    /// printable characters and is already line folded.
+    ///
+    /// When in doubt use [`HeaderValue::new`].
     pub fn dangerous_new_pre_encoded(
         name: HeaderName,
         raw_value: String,

src/message/header/special.rs

@@ -16,15 +16,18 @@ pub struct MimeVersion {
 pub const MIME_VERSION_1_0: MimeVersion = MimeVersion::new(1, 0);
 
 impl MimeVersion {
+    /// Build a new `MimeVersion` header
     pub const fn new(major: u8, minor: u8) -> Self {
         MimeVersion { major, minor }
     }
 
+    /// Get the `major` value of this `MimeVersion` header.
     #[inline]
     pub const fn major(self) -> u8 {
         self.major
     }
 
+    /// Get the `minor` value of this `MimeVersion` header.
     #[inline]
     pub const fn minor(self) -> u8 {
         self.minor

src/transport/smtp/client/async_connection.rs

@@ -41,6 +41,7 @@ pub struct AsyncSmtpConnection {
 }
 
 impl AsyncSmtpConnection {
+    /// Get information about the server
     pub fn server_info(&self) -> &ServerInfo {
         &self.server_info
     }

src/transport/smtp/client/connection.rs

@@ -44,6 +44,7 @@ pub struct SmtpConnection {
 }
 
 impl SmtpConnection {
+    /// Get information about the server
     pub fn server_info(&self) -> &ServerInfo {
         &self.server_info
     }

src/transport/smtp/client/tls.rs

@@ -219,6 +219,7 @@ impl TlsParameters {
         TlsParametersBuilder::new(domain).build()
     }
 
+    /// Creates a new `TlsParameters` builder
     pub fn builder(domain: String) -> TlsParametersBuilder {
         TlsParametersBuilder::new(domain)
     }

src/transport/stub/mod.rs

@@ -53,6 +53,8 @@ use futures_util::lock::Mutex as FuturesMutex;
 use crate::AsyncTransport;
 use crate::{address::Envelope, Transport};
 
+/// An error returned by the stub transport
+#[non_exhaustive]
 #[derive(Debug, Copy, Clone)]
 pub struct Error;