The original docstring is a complete red herring... yours is much better, but I'd go one further and include an example.