more readme and comprehensive docstrings