docs: def concat(objs, dim=None, data_vars='all', coords='different',
             compat='equals', positions=None, indexers=None, mode=None,
             concat_over=None):
      """Concatenate xarray objects along a new or existing dimension.
  
      Parameters
      ----------
      objs : sequence of Dataset and DataArray objects
          xarray objects to concatenate together. Each object is expected to
          consist of variables and coordinates with matching shapes except for
          along the concatenated dimension.
      dim : str or DataArray or pandas.Index
          Name of the dimension to concatenate along. This can either be a new
          dimension name, in which case it is added along axis=0, or an existing
          dimension name, in which case the location of the dimension is
          unchanged. If dimension is provided as a DataArray or Index, its name
          is used as the dimension to concatenate along and the values are added
          as a coordinate.
      data_vars : {'minimal', 'different', 'all' or list of str}, optional
          These data variables will be concatenated together:
            * 'minimal': Only data variables in which the dimension already
              appears are included.
            * 'different': Data variables which are not equal (ignoring
              attributes) across all datasets are also concatenated (as well as
              all for which dimension already appears). Beware: this option may
              load the data payload of data variables into memory if they are not
              already loaded.
            * 'all': All data variables will be concatenated.
            * list of str: The listed data variables will be concatenated, in
              addition to the 'minimal' data variables.
          If objects are DataArrays, data_vars must be 'all'.
      coords : {'minimal', 'different', 'all' or list of str}, optional
          These coordinate variables will be concatenated together:
            * 'minimal': Only coordinates in which the dimension already appears
              are included.
            * 'different': Coordinates which are not equal (ignoring attributes)
              across all datasets are also concatenated (as well as all for which
              dimension already appears). Beware: this option may load the data
              payload of coordinate variables into memory if they are not already
              loaded.
            * 'all': All coordinate variables will be concatenated, except
              those corresponding to other dimensions.
            * list of str: The listed coordinate variables will be concatenated,
              in addition the 'minimal' coordinates.
      compat : {'equals', 'identical'}, optional
          String indicating how to compare non-concatenated variables and
          dataset global attributes for potential conflicts. 'equals' means
          that all variable values and dimensions must be the same;
          'identical' means that variable attributes and global attributes
          must also be equal.
      positions : None or list of integer arrays, optional
          List of integer arrays which specifies the integer positions to which
          to assign each dataset along the concatenated dimension. If not
          supplied, objects are concatenated in the provided order.
      indexers, mode, concat_over : deprecated
  
      Returns
      -------
      concatenated : type of objs
  
      See also
      --------
      merge
      auto_combine
      """
      # TODO: add join and ignore_index arguments copied from pandas.concat
      # TODO: support concatenating scalar coordinates even if the concatenated
      # dimension already exists
      from .dataset import Dataset
      from .dataarray import DataArray
  
      try:
          first_obj, objs = utils.peek_at(objs)
      except StopIteration:
          raise ValueError('must supply at least one object to concatenate')
  
      if dim is None:
          warnings.warn('the `dim` argument to `concat` will be required '
                        'in a future version of xarray; for now, setting it to '
                        "the old default of 'concat_dim'",
                        FutureWarning, stacklevel=2)
          dim = 'concat_dims'
  
      if indexers is not None:  # pragma: nocover
          warnings.warn('indexers has been renamed to positions; the alias '
                        'will be removed in a future version of xarray',
                        FutureWarning, stacklevel=2)
          positions = indexers
  
      if mode is not None:
          raise ValueError('`mode` is no longer a valid argument to '
                           'xarray.concat; it has been split into the '
                           '`data_vars` and `coords` arguments')
      if concat_over is not None:
          raise ValueError('`concat_over` is no longer a valid argument to '
                           'xarray.concat; it has been split into the '
                           '`data_vars` and `coords` arguments')
  
      if isinstance(first_obj, DataArray):
          f = _dataarray_concat
      elif isinstance(first_obj, Dataset):
          f = _dataset_concat
      else:
          raise TypeError('can only concatenate xarray Dataset and DataArray '
                          'objects, got %s' % type(first_obj))
      return f(objs, dim, data_vars, coords, compat, positions)