fixing and documenting options and updating tests for new return values