refactor(api): cleand thinks up and added documentation

5 files changed, 51 insertions, 63 deletions

diff --git a/Cargo.toml b/Cargo.toml
index e343bdd..b8d1315 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -3,9 +3,9 @@ authors = ["Philipp Korber <p.korber@1aim.com>"]
 name = "mail-smtp"
 version = "0.1.0"
 categories = []
-description = "combines mail-codec with new-tokio-smtp"
+description = "[internal/mail-api] combines mail-types with new-tokio-smtp"
 documentation = "https://docs.rs/mail-smtp"
-keywords = ["mail", "smtp", "send" ]
+keywords = ["mail-api"]
 license = "MIT OR Apache-2.0"
 readme = "./README.md"
 repository = "https://github.com/1aim/mail-smtp"
diff --git a/src/error.rs b/src/error.rs
index cf51918..9ad1a74 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -46,22 +46,22 @@ impl From<LogicError> for MailSendError {
 #[derive(Debug, Fail)]
 pub enum TransportError {
 
-    // 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
+    /// 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
     #[fail(display = "{}", _0)]
     Connecting(ConnectingFailed),
 
-    // 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
+    /// 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
     #[fail(display = "{}", _0)]
     Io(std_io::Error)
 }
diff --git a/src/lib.rs b/src/lib.rs
index 83f5dba..0e047f5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -9,8 +9,8 @@ extern crate failure;
 mod resolve_all;
 
 pub mod error;
-mod common;
-mod encode;
+mod request;
+mod send_mail;
 
-pub use self::common::*;
-pub use self::encode::*;
\ No newline at end of file
+pub use self::request::*;
+pub use self::send_mail::*;
\ No newline at end of file
diff --git a/src/common.rs b/src/request.rs
index e9b9493..bcfede4 100644
--- a/src/common.rs
+++ b/src/request.rs
@@ -1,4 +1,3 @@
-//! This modules contains some of the data types used, like e.g. Response, Request, Envelop etc.
 use std::mem;
 
 use new_tokio_smtp::send_mail::{
@@ -7,7 +6,6 @@ use new_tokio_smtp::send_mail::{
     EnvelopData
 };
 
-
 use mail_common::MailType;
 use mail_common::encoder::{EncodingBuffer, EncodableInHeader};
 use mail_common::error::EncodingError;
@@ -18,14 +16,6 @@ use mail::Mail;
 use mail::error::MailError;
 
 
-
-
-// pub type MailSendResult = Result<MailResponse, MailSendError>;
-// pub(crate) type Handle2ServiceMsg = (MailRequest, oneshot::Sender<MailSendResult>);
-
-// #[derive(Debug, Clone)]
-// pub struct MailResponse;
-
 #[derive(Clone, Debug)]
 pub struct MailRequest {
     mail: Mail,
diff --git a/src/encode.rs b/src/send_mail.rs
index d6a92c2..fab3762 100644
--- a/src/encode.rs
+++ b/src/send_mail.rs
@@ -1,33 +1,3 @@
-
-/*
-
-
-       ↓
-  ---[][][]--------------------------            \
-  |    ↓            <<sequential>>  |             \
-  |    ↓                            |              \
-  | (create envelop)                |  \            |
-  |    ↓                            |  | 1. func    |
-  | (into encodable mail)           |  /            |
-  |    ↓ [envelop, encodable mail]  |                > 3. encode_mails
-  | (offload encode mail)           |  > 2. func    |
-  |    ↓ [envelop, future->Vec<u8>] |               |
-  ---[][][]--------------------------              /
-       ↓
-  [Future<Vec<Result<>>]............/ we don't want a stream here all encoding should     \
-       ↓                            | be already done, so that there are no large periods |
-       ↓                            \ where the smtp connection is open and pending       /
-       ↓
-  ---[][][]--------------------------             \
-  |    ↓       <<async/sequential>> |              \
-  |    ↓                            |               |
-  | (send mail)                     |                > send_mails
-  |    ↓                            |               |
-  |   <ok?> →→no→→ (add to failures)|               |
-  |    ↓ yes                        |              /
-  ---[][][]--------------------------             /
-       ↓
-*/
 use std::iter::FromIterator;
 use std::vec;
 
@@ -45,11 +15,26 @@ use ::common::MailRequest;
 use ::error::{MailSendError, TransportError};
 
 
+/// Result of encoding a mail
 pub type EncodeMailResult = Result<smtp::MailEnvelop, MailError>;
 
-// errors:
-// - EnvelopFromMailError
-// - MailError
+/// creates a futures 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.
+///
+/// # 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
+///
 pub fn encode_mails<I, C>(requests: I, ctx: &C)
     //TODO[futures/v>=0.2 | rust/! type]: use Never or !
     -> impl Future<Item=Vec<EncodeMailResult>, Error=()> + Send
@@ -89,9 +74,22 @@ pub fn encode_mails<I, C>(requests: I, ctx: &C)
     ResolveAll::from_iter(pending)
 }
 
+/// results of sending an encoded mail
 pub type SendMailResult = Result<(), MailSendError>;
 
-
+/// Sends all encoded mails through the given connection
+///
+/// This methods accepts a 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.
+///
+/// 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
+/// returned.
 pub fn send_encoded_mails<I>(con: Connection, mails: I)
     -> impl Future<
         Item=(Connection, Vec<SendMailResult>),