write better docstrings for some functions and do small cleanups