README.md, more return values consistent, some inline documentation

* Made return value policy concrete and applied new policy to several
  methods
* Removed some redundant methods (functions)
* Added some inline documentation using new "syntax"