add some comments, update some docs