Improve where docstring (#3836)

* improve the where docstring

* whatsnew

* improve assign docstring

* changes from @dcherian

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>`_.

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:

xarray/core/dataset.py

@@ -4392,8 +4392,6 @@ def assign(
 
         Examples
         --------
-        >>> import numpy as np
-        >>> import xarray as xr
         >>> x = xr.Dataset(
         ...     {
         ...         "temperature_c": (