elazarg's refactoring - simple changes

trying to break @elazarg 's refactoring (#143) into more manageable chunks

this PR contains:

* documentation improvements
* code comments
* removing unused imports