implemented @mhvk's suggestions from PR #2487
Add changelog entry
Update docstring to get rid of doctest failure