added extensive docstrings