Can you improve this docstring? I think it should be something resembling as documentation, not as a commit message.

Also, can you please include a "deprecated" warning (as there are in other docstrings), to keep up with the convention?