docstrings and better null handling
updated examples and restructured src