new docs
Add a bunch of tests to make sure I got the behavior right in the docs.
Merge pull request #11 from erinspice/docs

Update docs and extend unit tests