improved documentation to better reflect implementation