improve documentation to describe what is returned