improved comments and docstrings...