documentation and method signature changes to provide better context for usage
Merge pull request #2 from esuomi/documentation_and_scopes

documentation and method signature changes to provide better context for usage