improving documentation and minor refactoring