work in progress
more docs and comments