Document the new __repr__

Sorry I missed that one when it was decided upon in https://github.com/pydata/xarray/pull/1017, but I think the changes in repr should be documented somewhere (at the minimum in the “Breaking Changes” section of what’s new).

I just updated Salem for it to work well with xarray 0.9.0. The changes I had to make where quite small (that’s a good thing), but it took me a bit of time to understand what was going on.

What I found confusing is following:

In [1]: import xarray as xr
In [2]: ds = xr.DataArray([1, 2, 3]).to_dataset(name='var')
In [3]: ds
Out[3]: 
<xarray.Dataset>
Dimensions:  (dim_0: 3)
Coordinates:
  o dim_0    (dim_0) -
Data variables:
    var      (dim_0) int64 1 2 3

In [4]: 'dim_0' in ds.coords
Out[4]: False

dim_0is listed as coordinate, but 'dim_0' in ds.coords is False. I think it should remain like this, but maybe we should document somewhere what the “o” and “*” mean?

(possibly here)

[shoyer]

Any use case for dimensions which don’t have an index (i.e., an IndexVariable) but have coordinates? This would be confusing too:

I suppose we do something even more explicit, e.g., “Dimensions without a corresponding coordinate”. That feels too long to me, though.

I don’t like “Dimensions without index variable” because it emphasizes that they don’t have an index rather than that they don’t have a variable.

For now I think “Dimensions without coordinates” is my favorite.

[shoyer]

Sorry, I’m not sure to understand: do you mean you’d rather stay with the current behavior as you said in #1017 (comment) ?

I like the currently implemented behavior, which is the second bullet in https://github.com/pydata/xarray/pull/1017#issuecomment-249908900. We could potentially switch to the behavior of the first bullet (issue TypeError instead), but I think this would be less convenient.