documentation, tests and minor refactoring