From f02c8db8b96d2ca143f8a8c7e24961cd5dfcea47 Mon Sep 17 00:00:00 2001
From: Philipp Korber <p.korber@1aim.com>
Date: Thu, 6 Sep 2018 18:35:00 +0200
Subject: doc(send_mail) documented new api

---
 src/send_mail.rs | 43 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/src/send_mail.rs b/src/send_mail.rs
index 861159e..6646e13 100644
--- a/src/send_mail.rs
+++ b/src/send_mail.rs
@@ -27,6 +27,17 @@ use ::{
     request::MailRequest
 };
 
+/// Sends a given mail (request).
+///
+/// - This will use the given context to encode the mail.
+/// - Then it will use the connection config to open a connection to a mail
+///   server (likely a Mail Submission Agent (MSA)).
+/// - Following this it will send the mail to the server.
+/// - After which it will close the connection again.
+///
+/// You can use `MailRequest: From<Mail>` (i.e. `mail.into()`) to pass in
+/// a mail and derive the envelop data (from, to) from it or create your own
+/// mail request if different smtp envelop data is needed.
 pub fn send<A, S>(mail: MailRequest, conconf: ConnectionConfig<A, S>, ctx: impl Context)
     -> impl Future<Item=(), Error=MailSendError>
     where A: Cmd, S: SetupTls
@@ -40,6 +51,26 @@ pub fn send<A, S>(mail: MailRequest, conconf: ConnectionConfig<A, S>, ctx: impl
     fut
 }
 
+/// Sends a batch of mails to a server.
+///
+/// - This will use the given context to encode all mails.
+/// - After which it will use the connection config to open a connection
+///   to the server (like a Mail Submission Agent (MSA)).
+/// - Then it will start sending mails.
+///   - If a mail fails because of an error code but setting up the connection
+///     (which includes auth) didn't fail then others mails in the input will
+///     still be send
+///   - If the connection is broken because setting it up failed or it was
+///     interrupted, then the mail at which place it was noticed will return
+///     the given error and all later mails will return a I/0-Error with the
+///     `ErrorKind::NoConnection`
+/// - It will return a `Stream` which when polled will send the mails
+///   and return results _in the order the mails had been supplied_. So
+///   for each mail there will be exactly one result.
+/// - Once the stream is completed the connection will automatically be
+///   closed (even if the stream is not yet dropped, it closes it the
+///   moment it notices that there are no more mails to send!)
+///
 pub fn send_batch<A, S, C>(
     mails: Vec<MailRequest>,
     conconf: ConnectionConfig<A, S>,
@@ -63,7 +94,17 @@ fn collect_res<S, E>(stream: S) -> impl Future<Item=Vec<Result<S::Item, S::Error
     stream.then(|res| Ok(res)).collect()
 }
 
-
+/// Turns a `MailRequest` into a future resolving to a `MailEnvelop`.
+///
+/// This function is mainly used internally for `send`, `send_batch`
+/// but can be used by other libraries when `send`/`send_batch` doesn't
+/// quite match their use case. E.g. if they want to have a connection
+/// pool and instead of `connect->send->quit` want to have something like
+/// `take_from_pool->test->send->place_back_to_pool`, in which case they
+/// probably would want to do something along the lines of using encode
+/// then take a connection, test it, use the mail envelops with `new-tokio-smtp`'s
+/// `SendAllMails` stream with a `on_completion` handler which places it
+/// back in the pool.
 pub fn encode<C>(request: MailRequest, ctx: C)
     -> impl Future<Item=MailEnvelop, Error=MailSendError>
     where C: Context
-- 
cgit v1.2.3