From 5548c1e13ad076196d06a9b99cff0dcc4ef2be5e Mon Sep 17 00:00:00 2001
From: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>
Date: Thu, 19 Mar 2020 17:29:58 -0400
Subject: [PATCH] Improve where docstring (#3836)

* improve the where docstring

* whatsnew

* improve assign docstring

* changes from @dcherian
---
 doc/whats-new.rst          |  2 ++
 xarray/core/computation.py | 12 ++++++++----
 xarray/core/dataset.py     |  2 --
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/doc/whats-new.rst b/doc/whats-new.rst
index 8140288f350..6ae7398626f 100644
--- a/doc/whats-new.rst
+++ b/doc/whats-new.rst
@@ -94,6 +94,8 @@ Documentation
 - Fix documentation of :py:class:`DataArray` removing the deprecated mention
   that when omitted, `dims` are inferred from a `coords`-dict. (:pull:`3821`)
   By `Sander van Rijn <https://github.com/sjvrijn>`_.
+- Improve the :py:func:`where` docstring.
+  By `Maximilian Roos <https://github.com/max-sixty>`_
 - Update the installation instructions: only explicitly list recommended dependencies
   (:issue:`3756`).
   By `Mathias Hauser <https://github.com/mathause>`_.
diff --git a/xarray/core/computation.py b/xarray/core/computation.py
index f99764448da..f2941a3d0ba 100644
--- a/xarray/core/computation.py
+++ b/xarray/core/computation.py
@@ -1224,9 +1224,13 @@ def where(cond, x, y):
     ----------
     cond : scalar, array, Variable, DataArray or Dataset with boolean dtype
         When True, return values from `x`, otherwise returns values from `y`.
-    x, y : scalar, array, Variable, DataArray or Dataset
-        Values from which to choose. All dimension coordinates on these objects
-        must be aligned with each other and with `cond`.
+    x : scalar, array, Variable, DataArray or Dataset
+        values to choose from where `cond` is True
+    y : scalar, array, Variable, DataArray or Dataset
+        values to choose from where `cond` is False
+
+    All dimension coordinates on these objects must be aligned with each
+    other and with `cond`.
 
     Returns
     -------
@@ -1249,7 +1253,7 @@ def where(cond, x, y):
     Coordinates:
     * lat      (lat) int64 0 1 2 3 4 5 6 7 8 9
 
-    >>> xr.where(x < 0.5, x, 100 * x)
+    >>> xr.where(x < 0.5, x, x * 100)
     <xarray.DataArray 'sst' (lat: 10)>
     array([ 0. ,  0.1,  0.2,  0.3,  0.4, 50. , 60. , 70. , 80. , 90. ])
     Coordinates:
diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
index 7c218e209cb..a607f1aa164 100644
--- a/xarray/core/dataset.py
+++ b/xarray/core/dataset.py
@@ -4392,8 +4392,6 @@ def assign(
 
         Examples
         --------
-        >>> import numpy as np
-        >>> import xarray as xr
         >>> x = xr.Dataset(
         ...     {
         ...         "temperature_c": (