chore: proof read documentation and comments

3 files changed, 46 insertions, 55 deletions

diff --git a/README.md b/README.md
index edf8dba..f148293 100644
--- a/README.md
+++ b/README.md
@@ -3,9 +3,9 @@
 _[internal/mail-api] combines the `mail-types` crate with `new-tokio-smtp` crate_
 
 Mainly provides a `send_mails` method, which given a `ConnectionConfig` and
-a iterable source of `MailRequest`'s (e.g. `Vec<MailRequest>`) sends all mails
-to the server specified in the `ConnectionConfig`. This includes setting up
-the connection running a auth command, encoding all mails, sending each mail
+an iterable source of `MailRequest`'s (e.g. `Vec<MailRequest>`) sends all mails
+to the server specified in the `ConnectionConfig`.  This includes setting up
+the connection running an auth command, encoding all mails, sending each mail
 and closing the connection afterwards.
 
 Take a look at the [`mail-api` crate](https://github.com/1aim/mail-api) for more details.
diff --git a/src/error.rs b/src/error.rs
index 9ad1a74..24cccf1 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -6,27 +6,25 @@ use mail::error::MailError;
 
 #[derive(Debug, Fail)]
 pub enum MailSendError {
-    /// creating the mail failed
+    /// Creating the mail failed.
     ///
-    /// This can happen because of a number of reasons including:
-    ///
-    /// 1. missing header fields
-    /// 2. invalid header fields
-    /// 2. encoding header fields fails
-    /// 3. loading resources failed
-    ///    (resources like e.g. appendix, logo embedded in html mail, etc.)
+    /// This can happen for a number of reasons including:
     ///
+    /// 1. Missing header fields.
+    /// 2. Invalid header fields.
+    /// 2. Encoding header fields fails.
+    /// 3. Loading resources failed (resources like e.g. appendix, logo embedded in html mail, etc.)
     #[fail(display = "{}", _0)]
     Mail(MailError),
 
-    /// sending the mail failed
+    /// Sending the mail failed.
     ///
-    /// This can happen because of a number of reasons including:
-    /// 1. server rejects mail transaction because of send or receiver
+    /// This can happen for a number of reasons including:
+    /// 1. Server rejects mail transaction because of send or receiver
     ///    address or body data (e.g. body to long).
-    /// 2. mail address requires smtputf8 support, which is not given
-    /// 3. server rejects sending the mail for other reasons (it's
-    ///    closing, overloaded etc.)
+    /// 2. Mail address requires smtputf8 support, which is not given.
+    /// 3. Server rejects sending the mail for other reasons (it's
+    ///    closing, overloaded etc.).
     #[fail(display = "{}", _0)]
     Smtp(LogicError)
 }
@@ -45,23 +43,22 @@ impl From<LogicError> for MailSendError {
 
 #[derive(Debug, Fail)]
 pub enum TransportError {
-
-    /// Setting up the connection failed
+    /// Setting up the connection failed.
     ///
     /// Failures can include but are not limited to:
     ///
-    /// - connecting with tcp failed
-    /// - starting tls failed
-    /// - server does not want to be used (e.g. failure on sending EHLO)
-    /// - authentication failed
+    /// - Connecting with TCP failed.
+    /// - Starting TLS failed.
+    /// - Server does not want to be used (e.g. failure on sending EHLO).
+    /// - Authentication failed.
     #[fail(display = "{}", _0)]
     Connecting(ConnectingFailed),
 
-    /// An I/O-Error happened while using the connection
+    /// An I/O error happened while using the connection.
     ///
-    /// This is mainly for I/O-Error after the setup of the connection
-    /// was successful, which normally sending includes Ehlo and Auth
-    /// commands
+    /// This is mainly for I/O errors after the setup of the connection
+    /// was successful, which normally includes sending Ehlo and Auth
+    /// commands.
     #[fail(display = "{}", _0)]
     Io(std_io::Error)
 }
diff --git a/src/send_mail.rs b/src/send_mail.rs
index c2c0ce3..bd49fc6 100644
--- a/src/send_mail.rs
+++ b/src/send_mail.rs
@@ -14,26 +14,21 @@ use ::resolve_all::ResolveAll;
 use ::request::MailRequest;
 use ::error::{MailSendError, TransportError};
 
-/// Result of encoding a mail
+/// Result of encoding a mail.
 pub type EncodeMailResult = Result<smtp::MailEnvelop, MailError>;
 
-/// creates a futures which encodes all mails
+/// Creates a `Future` which encodes all mails.
 ///
-/// To encode the mails this functions turns
-/// mail every requests into mails with envelop data,
-/// then creates a future resolving when the mail is
-/// ready to be encoded and chain this result with
-/// offloading the actual encoding of each mail
-/// to a thread pool. Lastly all fo this futures
-/// are polled in parallel by the returned future.
+/// To encode the mails this function turns every `MailRequest` into mails with
+/// envelope data, then creates a `Future` resolving when the mail is ready to
+/// be encoded and chain this result by offloading the actual encoding of each
+/// mail to a thread pool. Lastly all of these `Future`s are polled in parallel
+/// by the returned `Future`.
 ///
 /// # Error
 ///
-/// The futures will never error, but it will
-/// resolve to a vector of results, representing
-/// the encoding result for each mail in the input
-/// separately
-///
+/// The `Future` will never error, but it will resolve to a vector of results
+/// representing the encoding result for each mail in the input separately.
 pub fn encode_mails(
     requests: impl IntoIterator<Item=MailRequest>,
     ctx: impl Context
@@ -75,21 +70,21 @@ pub fn encode_mails(
     ResolveAll::from_iter(pending)
 }
 
-/// results of sending an encoded mail
+/// Results of sending an encoded mail.
 pub type SendMailResult = Result<(), MailSendError>;
 
-/// Sends all encoded mails through the given connection
+/// Sends all encoded mails through the given `Connection`.
 ///
-/// This methods accepts a iterator of `EncodedMailResult`'s as it's
+/// This method accepts an iterator of `EncodedMailResult`'s as it's
 /// meant to be chained with `encode_mails`.
 ///
 /// # Error
 ///
-/// The returned future resolves to a vector of results, one for each mail
-/// send.
+/// The returned `Future` resolves to a vector of results, one for each mail
+/// sent.
 ///
-/// If a transport error happens (e.g. an I/O-Error) a tuple consisting of
-/// the Error, the already send mails and and iterator of the remaining mails is
+/// If a transport error happens (e.g. an I/O error) a tuple consisting of
+/// the `Error`, the already sent mails and and iterator of the remaining mails is
 /// returned.
 pub fn send_encoded_mails<I>(con: Connection, mails: I)
     -> impl Future<
@@ -121,18 +116,17 @@ pub fn send_encoded_mails<I>(con: Connection, mails: I)
     fut
 }
 
-/// Send mails _to a specific mail server_
+/// Send mails _to a specific mail server_.
 ///
 /// This encodes the mails, opens a connection, sends the mails over and
 /// closes the connection again.
 ///
-/// While this uses the `To` field of a mail to determine the smtp reveiver
-/// it does not resolve the server based on the mail address domain. This
-/// means it's best suite for sending to a Mail Submission Agent (MSA), but
-/// less for sending to a Mail Exchanger (MX).
-///
-/// Automatically handling Bcc/Cc is _not yet_ implemented.
+/// While this uses the `To` field of a mail to determine the SMTP receiver it
+/// does not resolve the server based on the mail address domain. This means
+/// it's best suited for sending to a Mail Submission Agent (MSA), but less for
+/// sending to a Mail Exchanger (MX).
 ///
+/// Automatically handling `Bcc`/`Cc` is _not yet_ implemented.
 pub fn send_mails(
     config: ConnectionConfig<impl Cmd, impl SetupTls>,
     requests: impl IntoIterator<Item=MailRequest>,