documenting how xarray.dot() interacts with coordinates

xarray/computation/computation.py

@@ -515,6 +515,14 @@ def dot(
     We recommend installing the optional ``opt_einsum`` package, or alternatively passing ``optimize=True``,
     which is passed through to ``np.einsum``, and works for most array backends.
 
+    **Coordinate Handling**
+
+    Like all xarray operations, ``dot`` automatically aligns array coordinates.
+    Coordinates are aligned by their **values**, not their order. By default, xarray uses
+    an inner join, so only overlapping coordinate values are included. With the default
+    ``arithmetic_join="inner"``, ``dot(a, b)`` is mathematically equivalent to ``(a * b).sum()``
+    over the specified dimensions. See :ref:`math automatic alignment` for more details.
+
     Examples
     --------
     >>> da_a = xr.DataArray(np.arange(3 * 2).reshape(3, 2), dims=["a", "b"])
@@ -572,6 +580,37 @@ def dot(
     >>> xr.dot(da_a, da_b, dim=...)
     <xarray.DataArray ()> Size: 8B
     array(235)
+
+    **Coordinate alignment examples:**
+
+    Coordinates are aligned by their values, not their order:
+
+    >>> x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])])
+    >>> y = xr.DataArray([2, 20], coords=[("foo", ["b", "a"])])
+    >>> xr.dot(x, y)
+    <xarray.DataArray ()> Size: 8B
+    array(40)
+
+    Non-overlapping coordinates are excluded from the computation:
+
+    >>> x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])])
+    >>> y = xr.DataArray([2, 30], coords=[("foo", ["b", "c"])])
+    >>> xr.dot(x, y)  # only 'b' overlaps: 10 * 2 = 20
+    <xarray.DataArray ()> Size: 8B
+    array(20)
+
+    Dimensions not involved in the dot product keep their coordinates:
+
+    >>> x = xr.DataArray(
+    ...     [[1, 2], [3, 4]],
+    ...     coords=[("time", [0, 1]), ("space", ["IA", "IL"])],
+    ... )
+    >>> y = xr.DataArray([10, 20], coords=[("space", ["IA", "IL"])])
+    >>> xr.dot(x, y, dim="space")  # time coordinates are preserved
+    <xarray.DataArray (time: 2)> Size: 16B
+    array([ 50, 110])
+    Coordinates:
+      * time     (time) int64 16B 0 1
     """
     from xarray.core.dataarray import DataArray
 

xarray/core/dataarray.py

@@ -5163,6 +5163,11 @@ def dot(
         dot
         numpy.tensordot
 
+        Notes
+        -----
+        This method automatically aligns coordinates by their values (not their order).
+        See :ref:`math automatic alignment` and :py:func:`xarray.dot` for more details.
+
         Examples
         --------
         >>> da_vals = np.arange(6 * 5 * 4).reshape((6, 5, 4))
@@ -5180,6 +5185,14 @@ def dot(
         >>> dot_result.dims
         ('x', 'y')
 
+        Coordinates are aligned by their values:
+
+        >>> x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])])
+        >>> y = xr.DataArray([2, 20], coords=[("foo", ["b", "a"])])
+        >>> x.dot(y)
+        <xarray.DataArray ()> Size: 8B
+        array(40)
+
         """
         if isinstance(other, Dataset):
             raise NotImplementedError(