update docs to match API, fix discrepancy
Merge pull request #552 from muffinista/user_docs

update docs to match API, fix discrepancy