Adding docstrings and error check to fix #471

This still implements the method taking as arguments both `old_ids` and `new_ids`