adds new return value, fixes docs