WIP documentation audit: ember-states/lib/state.js

PR for the ember API documentation audit.

If this looks good, let me know and I will do more files.

If there is a specific documentation style guide to read please let me know. Was a little uncertain about private events but at the very least it seems like every function should have comment preamble.