made another pass through the API docs clarifying and adding example code
Merge pull request #110 from cbare/api_docs_another_pass

made another pass through the API docs clarifying and adding example cod...