some refactoring and documentation