write better docstrings for some functions and other trivial changes