More docstrings. a few (untested) refactorings to make the function names more self documentating.