concat documentation

[ivorblockley]

It is currently documented that each object to be concatenated via xarray.concat():

is expected to consist of variables and coordinates with matching shapes except for along the concatenated dimension

While this might be the ideal, I'm wondering if this statement is misleading as clearly concat supports multiple join methods, with the default "outer" method able to handle variables/coordinates of differing shapes, preserving all the coordinates.

Should the documentation be updated to better clarify requirements of input objs?

For the sake of clarity, here is a simple example of xr.concat correctly handling DataArrays with different shapes along the non-concatenated dimension:

import numpy as np
import xarray as xr

da_list = []
for i in range(2):
    data = i * 100 + np.arange(i + 2).reshape(i + 2, 1)
    da = xr.DataArray(
        data=data,
        coords={"station_id": range(i + 2), "time": [i], "height": 2},
        dims=("station_id", "time"),
    )
    da_list.append(da)

da_list has two DataArrays with different shapes:

[
<xarray.DataArray (station_id: 2, time: 1)>
array([[0], [1]])
Coordinates:
  * station_id  (station_id) int64 0 1
  * time        (time) int64 0
    height      int64 2, 

<xarray.DataArray (station_id: 3, time: 1)>
array([[100], [101], [102]])
Coordinates:
  * station_id  (station_id) int64 0 1 2
  * time        (time) int64 1
    height      int64 2
]

A xr.concat(da_list, dim="time", join="outer") yields an intuitive result:

<xarray.DataArray (station_id: 3, time: 2)>
array([[  0., 100.],
       [  1., 101.],
       [ nan, 102.]])
Coordinates:
  * station_id  (station_id) int64 0 1 2
  * time        (time) int64 0 1
    height      int64 2

[TomNicholas]

I think yes, this definitely could be clarified. We would welcome a PR to do so if you are interested! Another place to update with the clarification might be on the terminology page.