refactoring, documentation and style fixes