improved documentation and comments