From 4059e5002d79fab918d04eb6ff624336c149ba12 Mon Sep 17 00:00:00 2001
From: Fletcher Nichol <fnichol@nichol.ca>
Date: Mon, 21 Sep 2015 12:49:30 -0600
Subject: [PATCH] Add documentation.

---
 Cargo.toml |  2 +-
 src/lib.rs | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 1 deletion(-)

diff --git a/Cargo.toml b/Cargo.toml
index 03a3a19..9b5ef05 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -9,9 +9,9 @@ path = "src/lib.rs"
 
 [[bin]]
 name = "names"
+doc = false
 
 [dependencies]
 # pending a release which includes https://github.com/kbknapp/clap-rs/pull/257
 clap = { git = "https://github.com/kbknapp/clap-rs", rev = "40104af" }
 rand = "0.3.0"
-
diff --git a/src/lib.rs b/src/lib.rs
index 747c8d7..cda080d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,65 @@
+//! This crate provides a generate that constructs random name strings suitable
+//! for use in container instances, project names, application instances, etc.
+//!
+//! # Usage
+//!
+//! This crate is [on crates.io](https://crates.io/crates/names) and can be
+//! used by adding `names` to your dependencies in your project's `Cargo.toml`
+//! file:
+//!
+//! ```toml
+//! [dependencies]
+//! names = "0.1.0"
+//! ```
+//!
+//! and this to your crate root:
+//!
+//! ```
+//! extern crate names;
+//! ```
+//!
+//! # Example: painless defaults
+//!
+//! The easiest way to get started is to use the default `Generator` to return
+//! a name:
+//!
+//! ```
+//! use names::Generator;
+//!
+//! let generator = Generator::default();
+//! println!("Your project is: {}", generator.name());
+//! // #=> "rusty-nail"
+//! ```
+//!
+//! If more randomness is required, you can generate a name with a trailing
+//! 4-digit number:
+//!
+//! ```
+//! use names::Generator;
+//!
+//! let generator = Generator::default();
+//! println!("Your project is: {}", generator.name_with_number());
+//! // #=> "pushy-pencil-5602"
+//! ```
+//!
+//! # Example: with custom dictionaries
+//!
+//! If you would rather supply your own custom adjective and noun word lists,
+//! you can provide your own by supplying 2 `Dictionary` structs. For example,
+//! this returns only one result:
+//!
+//! ```
+//! use names::{Dictionary, Generator};
+//!
+//! let adjectives = &["imaginary"];
+//! let nouns = &["roll"];
+//! let generator = Generator::new(
+//!     Dictionary::new(adjectives),
+//!     Dictionary::new(nouns));
+//!
+//! assert_eq!("imaginary-roll", generator.name());
+//! ```
+
 extern crate rand;
 
 use rand::Rng;
@@ -5,6 +67,7 @@ use rand::Rng;
 mod adjectives;
 mod nouns;
 
+/// A `Dictionary` is collection of words.
 pub struct Dictionary<'a> {
     words: &'a [&'a str],
 }
@@ -19,16 +82,48 @@ impl<'a> Dictionary<'a> {
     }
 }
 
+/// A random name generator which combines an adjective, a noun, and an
+/// optional number.
+///
+/// A `Generator` takes a `Dictionary` of adjectives and a `Dictionary` of
+/// nouns.
 pub struct Generator<'a> {
     adjectives: Dictionary<'a>,
     nouns: Dictionary<'a>,
 }
 
 impl<'a> Generator<'a> {
+    /// Constructs a new `Generator<'a>`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use names::{Dictionary, Generator};
+    ///
+    /// let adjective_words = &["sassy"];
+    /// let noun_words = &["clocks"];
+    ///
+    /// let adjectives = Dictionary::new(adjective_words);
+    /// let nouns = Dictionary::new(noun_words);
+    ///
+    /// let generator = Generator::new(adjectives, nouns);
+    ///
+    /// assert_eq!("sassy-clocks", generator.name());
+    /// ```
     pub fn new(adjectives: Dictionary<'a>, nouns: Dictionary<'a>) -> Generator<'a> {
         Generator { adjectives: adjectives, nouns: nouns }
     }
 
+    /// Construct and returns a default `Generator<'a>` containing a large
+    /// collection of adjectives and nouns.
+    ///
+    /// ```
+    /// use names::Generator;
+    ///
+    /// let generator = Generator::default();
+    ///
+    /// println!("My new name is: {}", generator.name());
+    /// ```
     pub fn default() -> Generator<'a> {
         Generator::new(
             Dictionary::new(adjectives::LIST),