update documentation and comments