clean up TODOs and add some detail to documentation