DOC: Improve coarsen docstring with detailed reduction requirements

[VedantMadane]

Summary

Improves the docstring for dask.array.coarsen by providing detailed documentation of the reduction function requirements.

Changes

• Clarify that the reduction function must:
  • Accept an array as the first positional argument (matching the chunk array type)
  • Accept an axis keyword argument with a tuple of integer axes
  • Return an array of the same type as the input
• Document the trim_excess parameter
• Document that **kwargs are passed to the reduction function
• Add a Returns section

Motivation

As noted in the issue, the original docstring only said 'Function like np.sum, np.mean, etc...' which doesn't clearly explain what properties a reduction function needs to have.

Closes #9825

[github-actions]

Unit Test Results

See test report for an extended history of previous test failures. This is useful for diagnosing flaky tests.

     25 files  ±0       25 suites  ±0   6h 57m 3s ⏱️ - 7m 1s
 19 914 tests ±0   18 481 ✅ ±0   1 433 💤 ±0  0 ❌ ±0 
379 353 runs  ±0  332 083 ✅  - 3  47 270 💤 +3  0 ❌ ±0 

Results for commit 1d9f29e. ± Comparison against base commit ba5045e.

♻️ This comment has been updated with latest results.

[VedantMadane]

Hi @dask, I've updated this PR. Could you please take a look when you have a moment? Thank you!

[jacobtomlinson]

@jrbourbeau given your comments on the issue that this closes would you have some time to review the PR? My guess from the PR description is that this is vibe-coded, so it would be good to check the docs actually match the functionality here.

[VedantMadane]

CI maintenance: rebased onto latest main

This is a DOC-only PR (dask/array/chunk.py coarsen docstring).

What I did

1. Checked out docs-coarsen-docstring from the fork
2. Rebased onto latest main (ba5045e00) — branch was ~62 commits behind after the May merge
3. Kept the single DOC commit (clean cherry-pick; no conflicts)
4. Ran lightweight pre-commit on the touched file — all passed (ruff, black, mypy, eof-fixer)
5. Force-with-lease push: 8946a4a38 → 1d9f29e6c

Notes on prior red matrix

• pre-commit hooks, doctest, and mindeps jobs were already green on the previous head
• Full OS/Python test matrix failures looked consistent with a stale branch vs main rather than docstring content
• Scope intentionally not expanded to fix unrelated dask CI

CI should re-run on the rebased tip. No merge performed.