move the docstring to the top, remove an old comment
throw exceptions instead of returning none