Add docs to reindex_like re broadcasting (#8327)

* Add docs to `reindex_like` re broadcasting

This wasn't clear to me so I added some examples & a reference to `broadcast_like`

Author: max-sixty

xarray/core/dataarray.py

@@ -1859,8 +1859,10 @@ def reindex_like(
         copy: bool = True,
         fill_value=dtypes.NA,
     ) -> Self:
-        """Conform this object onto the indexes of another object, filling in
-        missing values with ``fill_value``. The default fill value is NaN.
+        """
+        Conform this object onto the indexes of another object, for indexes which the
+        objects share. Missing values are filled with ``fill_value``. The default fill
+        value is NaN.
 
         Parameters
         ----------
@@ -1948,20 +1950,14 @@ def reindex_like(
           * x        (x) int64 40 30 20 10
           * y        (y) int64 90 80 70
 
-        Reindexing with the other array having coordinates which the source array doesn't have:
+        Reindexing with the other array having additional coordinates:
 
-        >>> data = np.arange(12).reshape(4, 3)
-        >>> da1 = xr.DataArray(
-        ...     data=data,
-        ...     dims=["x", "y"],
-        ...     coords={"x": [10, 20, 30, 40], "y": [70, 80, 90]},
-        ... )
-        >>> da2 = xr.DataArray(
+        >>> da3 = xr.DataArray(
         ...     data=data,
         ...     dims=["x", "y"],
         ...     coords={"x": [20, 10, 29, 39], "y": [70, 80, 90]},
         ... )
-        >>> da1.reindex_like(da2)
+        >>> da1.reindex_like(da3)
         <xarray.DataArray (x: 4, y: 3)>
         array([[ 3.,  4.,  5.],
                [ 0.,  1.,  2.],
@@ -1973,7 +1969,7 @@ def reindex_like(
 
         Filling missing values with the previous valid index with respect to the coordinates' value:
 
-        >>> da1.reindex_like(da2, method="ffill")
+        >>> da1.reindex_like(da3, method="ffill")
         <xarray.DataArray (x: 4, y: 3)>
         array([[3, 4, 5],
                [0, 1, 2],
@@ -1985,7 +1981,7 @@ def reindex_like(
 
         Filling missing values while tolerating specified error for inexact matches:
 
-        >>> da1.reindex_like(da2, method="ffill", tolerance=5)
+        >>> da1.reindex_like(da3, method="ffill", tolerance=5)
         <xarray.DataArray (x: 4, y: 3)>
         array([[ 3.,  4.,  5.],
                [ 0.,  1.,  2.],
@@ -1997,7 +1993,7 @@ def reindex_like(
 
         Filling missing values with manually specified values:
 
-        >>> da1.reindex_like(da2, fill_value=19)
+        >>> da1.reindex_like(da3, fill_value=19)
         <xarray.DataArray (x: 4, y: 3)>
         array([[ 3,  4,  5],
                [ 0,  1,  2],
@@ -2007,9 +2003,28 @@ def reindex_like(
           * x        (x) int64 20 10 29 39
           * y        (y) int64 70 80 90
 
+        Note that unlike ``broadcast_like``, ``reindex_like`` doesn't create new dimensions:
+
+        >>> da1.sel(x=20)
+        <xarray.DataArray (y: 3)>
+        array([3, 4, 5])
+        Coordinates:
+            x        int64 20
+          * y        (y) int64 70 80 90
+
+        ...so ``b`` in not added here:
+
+        >>> da1.sel(x=20).reindex_like(da1)
+        <xarray.DataArray (y: 3)>
+        array([3, 4, 5])
+        Coordinates:
+            x        int64 20
+          * y        (y) int64 70 80 90
+
         See Also
         --------
         DataArray.reindex
+        DataArray.broadcast_like
         align
         """
         return alignment.reindex_like(

xarray/core/dataset.py

@@ -3422,8 +3422,10 @@ def reindex_like(
         copy: bool = True,
         fill_value: Any = xrdtypes.NA,
     ) -> Self:
-        """Conform this object onto the indexes of another object, filling in
-        missing values with ``fill_value``. The default fill value is NaN.
+        """
+        Conform this object onto the indexes of another object, for indexes which the
+        objects share. Missing values are filled with ``fill_value``. The default fill
+        value is NaN.
 
         Parameters
         ----------
@@ -3469,7 +3471,9 @@ def reindex_like(
         See Also
         --------
         Dataset.reindex
+        DataArray.reindex_like
         align
+
         """
         return alignment.reindex_like(
             self,