From 8df7b8b1604bb340f25c58005e1b424255012495 Mon Sep 17 00:00:00 2001
From: Philipp Korber <p.korber@1aim.com>
Date: Wed, 22 Aug 2018 19:40:12 +0200
Subject: doc: more api doc

---
 README.md      | 17 ++++++-----------
 src/error.rs   | 16 ++++++++++++++++
 src/lib.rs     | 22 ++++++++++++++++++++--
 src/request.rs | 10 +++++++++-
 4 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 485865e..83d9b0e 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,9 @@
 # mail-smtp &emsp;
 
-_[internal/mail-api] combines the `mail-types` crate with `new-tokio-smtp` crate_
+**Allows sending `mail-types` `Mail`'s through  `new-tokio-smtp`**
 
-Mainly provides a `send_mails` method, which given a `ConnectionConfig` and
-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.
-
-Documentation can be [viewed on docs.rs](https://docs.rs/mail-smtp).
-
-## Example
 
 This library binds together `new-tokio-smtp` and the `mail` crates.
 
@@ -76,6 +67,10 @@ fn main() {
 ```
 
 
+## Documentation
+
+Documentation can be [viewed on docs.rs](https://docs.rs/mail-smtp).
+(once published)
 
 ## License
 
diff --git a/src/error.rs b/src/error.rs
index 24cccf1..850e0ee 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,9 +1,15 @@
+//! Module containing all custom errors.
 use std::{io as std_io};
 
 use new_tokio_smtp::error::{ConnectingFailed, LogicError};
 use mail::error::MailError;
 
 
+/// Error used when sending a mail fails.
+///
+/// Failing to encode a mail before sending
+/// it also counts as a `MailSendError`, as
+/// it's done "on the fly" when sending a mail.
 #[derive(Debug, Fail)]
 pub enum MailSendError {
     /// Creating the mail failed.
@@ -41,6 +47,16 @@ impl From<LogicError> for MailSendError {
     }
 }
 
+/// Error returned when something on the transport layer failed.
+///
+/// Thinks causing this error include:
+///
+/// - TLS required but not supported by server
+/// - authentication not valid
+/// - connection "broke" (e.g. because you
+///   internet connection is gone or the server
+///   crashed)
+///
 #[derive(Debug, Fail)]
 pub enum TransportError {
     /// Setting up the connection failed.
diff --git a/src/lib.rs b/src/lib.rs
index ef30887..edbb6b2 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -74,14 +74,32 @@ pub use self::request::MailRequest;
 #[cfg(feature="extended-api")]
 pub use self::request::derive_envelop_data_from_mail;
 
-pub use self::send_mail::{send_mails, SendMailResult};
+pub use self::send_mail::{
+    send_mails,
+    SendMailResult
+};
 #[cfg(feature="extended-api")]
 pub use self::send_mail::{encode_mails, send_encoded_mails};
 
 
 pub use new_tokio_smtp::{ConnectionConfig, ConnectionBuilder};
-pub use new_tokio_smtp::command::auth;
+
+pub mod auth {
+    //! Module containing authentification commands/methods.
+    //!
+    //! This Module is re-exported from `new-tokio-smtp` for
+    //! ease of use.
+
+    pub use new_tokio_smtp::command::auth::*;
+
+    /// Auth command for not doing anything on auth.
+    //FIXME: this currently still sends the noop cmd,
+    // replace it with some new "NoCommand" command.
+    pub type NoAuth = ::new_tokio_smtp::command::Noop;
+}
+
 pub mod misc {
+    //! A small collection of usefull types re-exported from `new-tokio-smtp`.
     pub use new_tokio_smtp::ClientId;
     pub use new_tokio_smtp::Domain;
     pub use new_tokio_smtp::AddressLiteral;
diff --git a/src/request.rs b/src/request.rs
index b5689d6..b6191f6 100644
--- a/src/request.rs
+++ b/src/request.rs
@@ -15,7 +15,15 @@ use headers::error::BuildInValidationError;
 use mail::Mail;
 use mail::error::MailError;
 
-
+/// This type contains a mail and potentially some envelop data.
+///
+/// It is needed as in some edge cases the smtp envelop data (i.e.
+/// smtp from and smtp recipient) can not be correctly derived
+/// from the mail.
+///
+/// The default usage is to directly turn a `Mail` into a `MailRequest`
+/// by either using  `MailRequest::new`, `MailRequest::from` or `Mail::into`.
+///
 #[derive(Clone, Debug)]
 pub struct MailRequest {
     mail: Mail,
-- 
cgit v1.2.3