improved doc string and error message
fixed the function to be based on sorting