Improve `engine` API doc: Types and misc

This is a new PR for #80, a follow-up for #96 , trying to improve docs of types and other misc fixes.

This PR would close #80 , leaving only more indeterminate work described [here](https://github.com/numenta/nupic.core/pull/96#issuecomment-42742433).