Improve the documentation of swap_dims (#3331)

* add an example to DataArray.swap_dims (and fix the documented return type)

* add an example to Dataset.swap_dims

* fix some errors in the swapped array's repr

* remove a newline

* mention changes in whatsnew

Author: keewis

doc/whats-new.rst

@@ -25,6 +25,10 @@ Bug fixes
   objects remain unaddressable by weakref in order to save memory.
   (:issue:`3317`) by `Guido Imperiale <https://github.com/crusaderky>`_.
 
+Documentation
+~~~~~~~~~~~~~
+- Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims`.
+  By `Justus Magin <https://github.com/keewis>`_.
 
 .. _whats-new.0.13.0:
 

xarray/core/dataarray.py

@@ -1453,9 +1453,26 @@ def swap_dims(self, dims_dict: Mapping[Hashable, Hashable]) -> "DataArray":
 
         Returns
         -------
-        swapped : Dataset
+        swapped : DataArray
             DataArray with swapped dimensions.
 
+        Examples
+        --------
+        >>> arr = xr.DataArray(data=[0, 1], dims="x",
+                               coords={"x": ["a", "b"], "y": ("x", [0, 1])})
+        >>> arr
+        <xarray.DataArray (x: 2)>
+        array([0, 1])
+        Coordinates:
+          * x        (x) <U1 'a' 'b'
+            y        (x) int64 0 1
+        >>> arr.swap_dims({"x": "y"})
+        <xarray.DataArray (y: 2)>
+        array([0, 1])
+        Coordinates:
+            x        (y) <U1 'a' 'b'
+          * y        (y) int64 0 1
+
         See Also
         --------
 

xarray/core/dataset.py

@@ -2679,6 +2679,29 @@ def swap_dims(
         swapped : Dataset
             Dataset with swapped dimensions.
 
+        Examples
+        --------
+        >>> ds = xr.Dataset(data_vars={"a": ("x", [5, 7]), "b": ("x", [0.1, 2.4])},
+                            coords={"x": ["a", "b"], "y": ("x", [0, 1])})
+        >>> ds
+        <xarray.Dataset>
+        Dimensions:  (x: 2)
+        Coordinates:
+          * x        (x) <U1 'a' 'b'
+            y        (x) int64 0 1
+        Data variables:
+            a        (x) int64 5 7
+            b        (x) float64 0.1 2.4
+        >>> ds.swap_dims({"x": "y"})
+        <xarray.Dataset>
+        Dimensions:  (y: 2)
+        Coordinates:
+            x        (y) <U1 'a' 'b'
+          * y        (y) int64 0 1
+        Data variables:
+            a        (y) int64 5 7
+            b        (y) float64 0.1 2.4
+
         See Also
         --------