significantly improves documentation

- most of the function parameter/internal argument names have changed for the better
- added lots of docstrings