improve documentation to remove all warnings