cleanup of docstrings and implementation of @astrofrog's suggestion