improve docstrings with examples and links

This is a (incomplete) checklist for #5816 to make it easier to find methods that are in need of examples and links to the narrative docs with further information (of course, changes to the docstrings of all other methods / functions part of the public API are also appreciated).

Good examples explicitly construct small xarray objects to make it easier to follow (e.g. use np.{ones,full,zeros} or the np.array constructor instead of np.random / loading from files) and show both input and output of the function.

Use

pytest --doctest-modules xarray --ignore xarray/tests/

to verify the examples, or push to a PR to have the CI do it for you (note that you will have much quicker feedback locally though).

To easily generate the expected output install pytest-accept (docs) in your dev environment and then run

pytest --doctest-modules FILE_NAME --accept || true

To link to other documentation pages we can use

:doc:`project:label`
    Description of the linked page

where we can leave out project if we link to somewhere within xarray's documentation. To figure out the label, we can either look at the source, search the output of python -m sphinx.ext.intersphinx https://docs.xarray.dev/en/latest/objects.inv, or use sphobjinv (install from PyPI):

sphobjinv search -su https://docs.xarray.dev/en/latest/ missing

Top-level functions:

• get_options
• decode_cf
• polyval
• unify_chunks
• infer_freq
• date_range

I/O:

• load_dataarray
• load_dataset
• open_dataarray
• open_dataset
• open_mfdataset

Contents:

• DataArray.assign_attrs
• Dataset.assign_attrs
• DataArray.expand_dims
• Dataset.expand_dims
• DataArray.drop_duplicates
• Dataset.drop_duplicates
• DataArray.drop_vars
• Dataset.drop_vars
• Dataset.drop_dims
• DataArray.convert_calendar
• Dataset.convert_calendar
• DataArray.set_coords
• Dataset.set_coords
• DataArray.reset_coords
• Dataset.reset_coords

Comparisons:

• DataArray.equals
• Dataset.equals
• DataArray.identical
• Dataset.identical
• DataArray.broadcast_equals
• Dataset.broadcast_equals

Dask:

• DataArray.compute
• Dataset.compute
• DataArray.chunk
• Dataset.chunk
• DataArray.persist
• Dataset.persist

Missing values:

• DataArray.bfill
• Dataset.bfill
• DataArray.ffill
• Dataset.ffill
• DataArray.fillna
• Dataset.fillna
• DataArray.dropna
• Dataset.dropna

Indexing:

• DataArray.loc (no docstring at all - came up in https://github.com/pydata/xarray/discussions/7528#discussion-4858556)
• DataArray.drop_isel
• DataArray.drop_sel
• DataArray.head
• Dataset.head
• DataArray.tail
• Dataset.tail
• DataArray.interp_like
• Dataset.interp_like
• DataArray.reindex_like
• Dataset.reindex_like
• Dataset.isel

Aggregations:

• Dataset.argmax
• Dataset.argmin
• DataArray.cumsum (intermediate to advanced)
• Dataset.cumsum (intermediate to advanced)
• DataArray.cumprod (intermediate to advanced)
• Dataset.cumprod (intermediate to advanced)
• DataArray.reduce
• Dataset.reduce

Choose an unchecked function from the listed top-level, I/O, contents, Dask, missing-values, indexing, or aggregation entries, then inspect its existing docstring and related narrative documentation. Use the provided pytest doctest command to verify examples and use the documented Sphinx or sphobjinv guidance to add links. Done means the selected docstring has clear input/output examples, valid links, and passing doctests.