doc: more api doc

3 files changed, 45 insertions, 3 deletions

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,