tidy up the docstrings and comments