improved documentation and readability