add more docstrings and trivial refactoring/var renaming