From a5fe56a081ef59a7fffd1408bb18df2c9dfb4d1e Mon Sep 17 00:00:00 2001
From: keewis <keewis@users.noreply.github.com>
Date: Sun, 22 Sep 2019 18:30:24 +0200
Subject: [PATCH] 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
---
 doc/whats-new.rst        |  4 ++++
 xarray/core/dataarray.py | 19 ++++++++++++++++++-
 xarray/core/dataset.py   | 23 +++++++++++++++++++++++
 3 files changed, 45 insertions(+), 1 deletion(-)

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