Update readme.markdown
slightly better api docs
Merge pull request #1 from jtremback/master

Slightly more better api docs