add a lot of documentation; code clean up