some refactorings to improve clarity
fixed broken docstring