fix the name of the return value in the swap_dims docstrings

[keewis]

• Tests added
• Passes black . && mypy . && flake8
• Fully documented, including whats-new.rst for all changes and api.rst for new API

[dcherian]

Thanks @keewis I just remembered issue #2838. I am sorry I didn't point this out earlier. It looks like we want to change this from swap_dims to rename_dims. Are you up for doing that?

I think the way to proceed would be to change the name of this method to rename_dims; add a new swap_dims method that raises a DeprecationWarning and calls the new rename_dims

[keewis]

from what I understand of how swap_dims works, that name change does not really reflect what it does:

>>> a = xr.DataArray(data=[0, 1], coords={"x": ["a", "b"], "x2": ("x", [0, 1])}, dims="x")
>>> a
<xarray.DataArray (x: 2)>
array([0, 1])
Coordinates:
  * x        (x) <U1 'a' 'b'
    x2       (x) int64 0 1
>>> a.swap_dims({"x": "x2"})
<xarray.DataArray (x2: 2)>
array([0, 1])
Coordinates:
    x        (x2) <U1 'a' 'b'
  * x2       (x2) int64 0 1

I think that rather than renaming swap_dims, an entirely new function named rename_dims (which Dataset got in #3045) would be better? Also, from #2838 it seems that adding examples to swap_dims should help?

[keewis]

oh, and I would certainly like to extend this PR to fix this (but only once #3238 is done)

[dcherian]

😳

[keewis]

say, would it help to add my example to the docstring? If so, should I open a new PR for that?

[dcherian]

Yes and yes.