Improve documentation

Based on my problems with the library I added some more documentation.

* Improve documentation
* Fix return values
--" again"