add lots of documentation and comments