add docstrings and some refactoring