doc: added lib level doc and example

2 files changed, 123 insertions, 0 deletions

diff --git a/README.md b/README.md
index f148293..485865e 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,71 @@ Take a look at the [`mail-api` crate](https://github.com/1aim/mail-api) for more
 
 Documentation can be [viewed on docs.rs](https://docs.rs/mail-smtp).
 
+## Example
+
+This library binds together `new-tokio-smtp` and the `mail` crates.
+
+It can be used to send mail given  as mail crates `Mail` instances
+to a Mail Submission Agent (MSA). It could, theoretically also
+be used to send to an MX, but this often needs additional functionality
+for reliable usage which is not part of this crate.
+
+For ease of use this crate re-exports some of the most commonly used
+parts from `new-tokio-smtp` including `ConnectionConfig`,
+`ConnectionBuilder`, all authentication commands/methods (the
+`auth` module) as well as useful types (in the `misc` module).
+
+The `send_mails` function is the simplest way to send a batch
+of mails. Nevertheless it doesn't directly accept `Mail` instances,
+instead it accepts `MailRequest` instances. This is needed, as
+the sender/recipient(s) specified through the `Mail` headers
+and those used fro smtp mail delivery are not necessary exactly
+the same (e.g. for bounce back mails and some no-reply setups).
+
+# Example
+
+```rust ,no_run
+extern crate futures;
+//if you use the mail facade use the re-exports from it instead
+extern crate mail_types;
+extern crate mail_smtp;
+#[macro_use] extern crate mail_headers;
+
+use futures::Future;
+use mail_headers::*;
+use mail_headers::components::Domain;
+use mail_types::{Mail, default_impl::simple_context};
+use mail_smtp::{send_mails, ConnectionConfig};
+
+fn main() {
+    // this is normally done _once per application instance_
+    // and then stored in e.g. a lazy_static. Also `Domain`
+    // will implement `FromStr` in the future.
+    let ctx = simple_context::new(
+        Domain::from_unchecked("example.com".to_owned(),
+        // This should be "world" unique for the given domain
+        // to assure message and content ids are world unique.
+        "asdkds".parse().unwrap()
+    ).unwrap();
+
+    let mut mail = Mail::plain_text("Some body").unwrap();
+    mail.set_headers(headers! {
+        _From: ["bla@example.com"],
+        _To: ["blub@example.com"],
+        Subject: "Some Mail"
+    }.unwrap()).unwrap();
+
+    // don't use unencrypted con for anything but testing and
+    // simplified examples
+    let con_config = ConnectionConfig::build_local_unencrypted().build();
+
+    let fut = send_mails(con_config, vec![mail.into()], ctx);
+    let results = fut.wait();
+}
+```
+
+
+
 ## License
 
 Licensed under either of
diff --git a/src/lib.rs b/src/lib.rs
index d70fabc..2d49ebf 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,61 @@
+//! This library binds together `new-tokio-smtp` and the `mail` crates.
+//!
+//! It can be used to send mail given  as mail crates `Mail` instances
+//! to a Mail Submission Agent (MSA). It could, theoretically also
+//! be used to send to an MX, but this often needs additional functionality
+//! for reliable usage which is not part of this crate.
+//!
+//! For ease of use this crate re-exports some of the most commonly used
+//! parts from `new-tokio-smtp` including `ConnectionConfig`,
+//! `ConnectionBuilder`, all authentication commands/methods (the
+//! `auth` module) as well as useful types (in the `misc` module).
+//!
+//! The `send_mails` function is the simplest way to send a batch
+//! of mails. Nevertheless it doesn't directly accept `Mail` instances,
+//! instead it accepts `MailRequest` instances. This is needed, as
+//! the sender/recipient(s) specified through the `Mail` headers
+//! and those used fro smtp mail delivery are not necessary exactly
+//! the same (e.g. for bounce back mails and some no-reply setups).
+//!
+//! # Example
+//!
+//! ```no_run
+//! extern crate futures;
+//! //if you use the mail facade use the re-exports from it instead
+//! extern crate mail_types;
+//! extern crate mail_smtp;
+//! #[macro_use] extern crate mail_headers;
+//!
+//! use futures::Future;
+//! use mail_headers::*;
+//! use mail_headers::components::Domain;
+//! use mail_types::{Mail, default_impl::simple_context};
+//! use mail_smtp::{send_mails, ConnectionConfig};
+//!
+//! # fn main() {
+//! // this is normally done _once per application instance_
+//! // and then stored in e.g. a lazy_static. Also `Domain`
+//! // will implement `FromStr` in the future.
+//! let ctx = simple_context::new(Domain::from_unchecked("example.com".to_owned()), "asdkds".parse().unwrap())
+//!     .unwrap();
+//!
+//! let mut mail = Mail::plain_text("Some body").unwrap();
+//! mail.set_headers(headers! {
+//!     _From: ["bla@example.com"],
+//!     _To: ["blub@example.com"],
+//!     Subject: "Some Mail"
+//! }.unwrap()).unwrap();
+//!
+//! // don't use unencrypted con for anything but testing and
+//! // simplified examples
+//! let con_config = ConnectionConfig::build_local_unencrypted().build();
+//!
+//! let fut = send_mails(con_config, vec![mail.into()], ctx);
+//! let results = fut.wait();
+//! # }
+//! ```
+//!
+//!
 extern crate futures;
 extern crate new_tokio_smtp;
 extern crate mail_types as mail;