issue_comments

OK. I totally agree with you.

The API now I propose is

```Python def expand_dims(self, dim=None, axis=0): """Return a new object with an additional axis (or axes) inserted at the corresponding position in the array shape.

    Parameters
    ----------
    dim : str, list of strs, tuple of strs, or None
        Name(s) of new dimension.
        If a list (or tuple) of strings is passed, multiple axes are inserted.
        In this case, axis argument should be 0 or same length of integers indicating new axes positions.
    axis : integer, list of integers or tuple of integers
        Axis position(s) where new axis is to be inserted (position(s) on the result array).
        If a list (or tuple) of integers is passed, multiple axes are inserted.
        In this case, dim arguments should be None or same length list.

    Returns
    -------
    expanded : same type as caller
        This object, but with an additional dimension.

    Raises
    -------
    ValueError:
           If the length of axis and dim are different.
           If the axis is a list containing identical integers
           If axis is invalid (larger than the original dimension+1)

```

I would switch the order of the method arguments.

I agree this. Do you think it is confusing if this method automatically detects the positional argument, i.e. if string is passed then it should be the axis name and an integer should be axis position.

I think that numpy-like API is most user-friendly, as like TensorFlow imitates them. I like to support da.expand_dims(0) if it is not confusing for users who don't care the axes order.

We might also consider supporting inserting multiple axes at once

I guess that the reason that numpy doesn't support multiple axes insertion is it brings additional ambugousity to the new axes positions; e.g. da.expand_dims([2,1]) could behave python da.expand_dims(2) da.expand_dims(1) or python da.expand_dims(1) da.expand_dims(2) the results differ. (It does not matter if user only specifies the labels or the list is in order.)

I hesitate this option actually.

Yes. How about the following? (I assume this is a method of xr.DataArray.)

```Python def expand_dims(self, axis=0, dim=None): """Return a new object with an additional dimension inserted at the corresponding position in the array shape.

    Parameters
    ----------
    axis : integer
        Position (amongst axes) where new axis is to be inserted.
    dim : str or None
        Name of new dimension.

    Returns
    -------
    expanded : same type as caller
        This object, but with an additional dimension.

```

I consider 2 types users; first type users always take care of the dimension order and the other just consider the dimension labels. The first type users may specify the new axis position as axis argument. The other may just pass the new dimension name regardless of its position, in which case the new dimension will be appended as the first dimension.

This API is similar to that of np.expand_dims and I believe its behavior is intuitive.