code readability and documentation fixes