issue_comments: 514118022

Thanks @zdgriffith. Yes it would be clearer to make that distinction. How about just adding a line:

concat_dim : str, or list of str, DataArray, Index or None, optional Dimensions to concatenate files along. You only need to provide this argument if any of the dimensions along which you want to concatenate is not a dimension in the original datasets, e.g., if you want to stack a collection of 2D arrays along a third dimension. Required for combine='nested', but not used for combine='by_coords'. ...

as None is a valid input, wouldn't it make more sense as an optional argument?

The reason it's not an optional argument to combine_nested is because currently None tells combine_nested to do something specific: merge datasets along that axis of the input instead of concatenating them. This is useful when you want to combine by some combination of concatenation and merging.

That's what

Set concat_dim=[..., None, ...] explicitly to disable concatenation along a particular dimension.

is supposed to be getting at, but obviously also needs to be clearer. Note None is only a valid input because it gets converted to [None] internally for convenience.