Description of coords type in documentation contradicts the example following it.

[dorchard]

What happened?

The data structures documentation in user guide states that:

• coords: a list or dictionary of coordinates. If a list, it should be a
  list of tuples where the first element is the dimension name and the second
  

  xarray/doc/user-guide/data-structures.rst

  Lines 57 to 59 in 48be376

  	- ``coords``: a list or dictionary of coordinates. If a list, it should be a
  	list of tuples where the first element is the dimension name and the second
  	element is the corresponding coordinate array_like object.

But the example immediately following it has a list of coords that is not a list of tuples:

locs = ["IA", "IL", "IN"]
times = pd.date_range("2000-01-01", periods=4)
foo = xr.DataArray(data, coords=[times, locs], dims=["time", "space"])

instead [times, locs] is a just a list of lists.

xarray/doc/user-guide/data-structures.rst

Lines 68 to 70 in 48be376

	locs = ["IA", "IL", "IN"]
	times = pd.date_range("2000-01-01", periods=4)
	foo = xr.DataArray(data, coords=[times, locs], dims=["time", "space"])

I believe the code is correct though so just the description of coords needs an update and should be clear that if you have just a list of coordinate lists, then the order of the outer list should match the order of the dims list.

What did you expect to happen?

Example not to contradict the description of the type.

Minimal Complete Verifiable Example

N/A

MVCE confirmation

• Minimal example — the example is as focused as reasonably possible to demonstrate the underlying issue in xarray.
• Complete example — the example is self-contained, including all data and the text of any traceback.
• Verifiable example — the example copy & pastes into an IPython prompt or Binder notebook, returning the result.
• New issue — a search of GitHub Issues suggests this is not a duplicate.
• Recent environment — the issue occurs with the latest version of xarray and its dependencies.

Relevant log output

N/A

Anything else we need to know?

No response

Environment

[welcome]

Thanks for opening your first issue here at xarray! Be sure to follow the issue template!
If you have an idea for a solution, we would really welcome a Pull Request with proposed changes.
See the Contributing Guide for more.
It may take us a while to respond here, but we really value your contribution. Contributors like you help make xarray better.
Thank you!

[max-sixty]

Good point!

I think the docs in the __init__ are correct, so we could just remove the incorrect description from the docs.

A PR would be v welcome if you'd be up for it...

xarray/xarray/core/dataset.py

Line 288 in 4d8bbee

coords : :py:class:`~xarray.Coordinates` or dict-like, optional