add docstrings and resolve TODOs