update readme and top level comments