improved comments/docstrings