From 50221ab2ea07b3fcf15c09320fe5585638da1735 Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Sat, 21 Sep 2019 14:53:49 +0200
Subject: [PATCH 1/5] add an example to DataArray.swap_dims (and fix the
 documented return type)

---
 xarray/core/dataarray.py | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
index e4379bd50fb..90e947d0a28 100644
--- a/xarray/core/dataarray.py
+++ b/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 (x2: 2)>
+        array([0, 1])
+        Coordinates:
+            x        (x2) <U1 'a' 'b'
+          * y        (x2) int64 0 1
+
         See Also
         --------
 

From 455968bed8d2edf4ecf7c31c2dddbba199e63110 Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Sat, 21 Sep 2019 15:07:05 +0200
Subject: [PATCH 2/5] add an example to Dataset.swap_dims

---
 xarray/core/dataset.py | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
index e01d83dd0a3..acb352b3fe3 100644
--- a/xarray/core/dataset.py
+++ b/xarray/core/dataset.py
@@ -2679,6 +2679,30 @@ 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
         --------
 

From 9029e5fdd5c3072393e607868928c4d28e163a94 Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Sun, 22 Sep 2019 00:49:09 +0200
Subject: [PATCH 3/5] fix some errors in the swapped array's repr

---
 xarray/core/dataarray.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
index 90e947d0a28..add2b1b6c01 100644
--- a/xarray/core/dataarray.py
+++ b/xarray/core/dataarray.py
@@ -1467,11 +1467,11 @@ def swap_dims(self, dims_dict: Mapping[Hashable, Hashable]) -> "DataArray":
           * x        (x) <U1 'a' 'b'
             y        (x) int64 0 1
         >>> arr.swap_dims({"x": "y"})
-        <xarray.DataArray (x2: 2)>
+        <xarray.DataArray (y: 2)>
         array([0, 1])
         Coordinates:
-            x        (x2) <U1 'a' 'b'
-          * y        (x2) int64 0 1
+            x        (y) <U1 'a' 'b'
+          * y        (y) int64 0 1
 
         See Also
         --------

From efb03f4ee46cdd23b8e8cf0a1aff01044e78c0bb Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Sun, 22 Sep 2019 13:33:07 +0200
Subject: [PATCH 4/5] remove a newline

---
 xarray/core/dataset.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
index acb352b3fe3..ea087ce3ce1 100644
--- a/xarray/core/dataset.py
+++ b/xarray/core/dataset.py
@@ -2702,7 +2702,6 @@ def swap_dims(
             a        (y) int64 5 7
             b        (y) float64 0.1 2.4
 
-
         See Also
         --------
 

From 0313df94474ef2073025290ef37e729347045d96 Mon Sep 17 00:00:00 2001
From: Keewis <keewis@posteo.de>
Date: Sun, 22 Sep 2019 13:33:38 +0200
Subject: [PATCH 5/5] mention changes in whatsnew

---
 doc/whats-new.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/whats-new.rst b/doc/whats-new.rst
index eeb768224e6..d8d3382675e 100644
--- a/doc/whats-new.rst
+++ b/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: