update docs for new methods and behavior
Merge pull request #241 from kenichi/doc

update docs for new methods and behavior