more refactoring and documentation