updated documentation and simplified returned value names