update lots of comments and documentation