docs/add docstrings to synchronous API

[d-v-b]

I add docstrings to the exported functions defined in api/synchronous.py, copy exactly the same functions in api/asynchronous.py, except for a few places where the sync / async functions diverge.

I also add a test to check that docstrings are identical, and another test to check that function signatures are identical, for said paired functions. These tests also get some exceptions for functions that are not quite identical.

closes #2475

TODO:

• Add unit tests and/or doctests in docstrings
• Add docstrings and API docs for any new/modified user-facing classes and functions
• New/modified features documented in docs/tutorial.rst
• Changes documented in docs/release.rst
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

[d-v-b]

note that some lower-level routines needed their function signatures updating -- it seems like Array.create wasn't fully aware that it takes int for chunks / chunk_shape

[dstansby]

Nice, and great that it caught some dodgy signatures. I left a couple of suggestions/questions

[dstansby]

If the signature of two functions is different, shouldn't the docstring be different too. ie., this list and the same list above in test_derived_docstrings should be the same?

In at least tree() this seems to be correct - the docstring for zarr.api.asynchronous.tree needs correcting to say it takes an AsyncGroup as input, at which point it will have a different docstring to zarr.api.synchronous.tree

[d-v-b]

yes i think you are right -- by construction all of the docstrings should be different in their return type annotation, and so this test is currently incorrect (fortunately I guarded for something like this outcome in the test docstring by stating "derived from" rather than "equal to")

[jhamman]

👏

[dstansby]

Marking as requested changes so we don't forget the test needs fixing (see #2549 (comment))

[d-v-b]

I removed the docstring / function signature tests, because I think they are too complex to implement properly right now. I think this is basically ready.