:shirt:

1 files changed, 46 insertions, 0 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 9cb8f82..3d72620 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2,6 +2,52 @@
 
 #![allow(unknown_lints)]
 
+//! Configuration is gathered by building a `Source` and then merging that source into the
+//! current state of the configuration.
+//!
+//! ```rust
+//! fn main() {
+//!     // Add environment variables that begin with RUST_
+//!     config::merge(config::Environment::new("RUST"));
+//!
+//!     // Add 'Settings.json'
+//!     config::merge(config::File::new("Settings", config::FileFormat::Json));
+//!
+//!     // Add 'Settings.$(RUST_ENV).json`
+//!     let name = format!("Settings.{}", config::get_str("env").unwrap());
+//!     config::merge(config::File::new(&name, config::FileFormat::Json));
+//! }
+//! ```
+//!
+//! Note that in the above example the calls to `config::merge` could have
+//! been re-ordered to influence the priority as each successive merge
+//! is evaluated on top of the previous.
+//!
+//! Configuration values can be retrieved with a call to `config::get` and then
+//! coerced into a type with `as_*`.
+//!
+//! ```toml
+//! # Settings.toml
+//! debug = 1
+//! ```
+//!
+//! ```rust
+//! fn main() {
+//!     // Add 'Settings.toml' (from above)
+//!     config::merge(config::File::new("Settings", config::FileFormat::Toml));
+//!
+//!     // Get 'debug' and coerce to a boolean
+//!     assert_eq!(config::get("debug").unwrap().as_bool(), Some(true));
+//!
+//!     // You can use a type suffix on `config::get` to simplify
+//!     assert_eq!(config::get_bool("debug"), Some(true));
+//!     assert_eq!(config::get_str("debug"), Some("true"));
+//! }
+//! ```
+//!
+//! See the [examples](https://github.com/mehcode/config-rs/tree/master/examples) for
+//! more usage information.
+
 #[cfg(feature = "toml")]
 extern crate toml;