Align public GeoTIFF docstrings with epic #2340 release contract

[brendancol]

Summary

• Adds a consistent [tier] marker (stable / advanced / experimental / internal-only) to every parameter on the seven public GeoTIFF entry points, drawn from epic Epic: GeoTIFF release contract and feature tiering #2340.
• Adds a short release-contract header to each docstring that points at docs/source/reference/release_gate_geotiff.rst (audit page) and docs/source/reference/geotiff_release_contract.rst (expected path once PR 2 lands).
• Drops language that implied broader support than the contract: full GDAL VRT parity, warped VRTs, stable GPU paths, stable LERC/J2K/LZ4/JPEG-in-TIFF. Experimental and internal-only paths name their opt-in kwarg inline.

Backend coverage

Docstrings only. No runtime change, so backend coverage of the underlying entry points is unchanged.

Test plan

• Every public entry point has at least one tier marker and a release-contract reference in its docstring.
• Existing docstring / contract test suite passes (test_compression_docstring_1644, test_supported_features_tiers_2137, test_release_gate_2321).
• No doctest examples were broken.

Closes #2346. Part of epic #2340 (PR 3 of 6).

[brendancol]

PR Review: Align public GeoTIFF docstrings with epic #2340 release contract

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• xrspatial/geotiff/__init__.py open_geotiff source param: the inline marker is "[stable for local file paths; advanced for HTTP/fsspec URIs; advanced for .vrt paths]" and does not tier the in-memory file-like buffer case (io.BytesIO). The function accepts that case but it is excluded from the dask / GPU / VRT / remote paths. Name the file-like case explicitly, probably as advanced, since it works but only on the eager numpy path.
• xrspatial/geotiff/__init__.py around lines 348-360: the bullet list tags JPEG-in-TIFF as [internal-only] and says the read path "only decodes files this library itself wrote." That is the writer contract. The reader can in principle decode any JPEG-in-TIFF, but the round-trip property only holds for files we wrote. Reword so the asymmetry is explicit: write is internal-only, read tolerates external JPEG-in-TIFF on a best-effort basis with no parity claim.
• xrspatial/geotiff/_backends/gpu.py gpu deprecated alias param: marked [internal-only]. The function-level tier is experimental; marking the deprecated alias as internal-only is defensible (callers should not use it), but experimental may be closer to intent here. The alias is in the public signature and emits a DeprecationWarning rather than refusing.

Nits (optional improvements)

• xrspatial/geotiff/_writers/eager.py streaming_buffer_bytes: tagged [stable]. The kwarg only matters for dask-backed inputs. Note that explicitly so callers know it is a no-op for numpy.
• xrspatial/geotiff/_vrt.py read_vrt / write_vrt (the internal symbols): the new [internal-only] header is good. Add an explicit "do not call directly" line at the top so anyone arriving from _backends/vrt.py does not assume the internal symbol carries the same advanced tier.
• Several params (e.g. name, band on multiple entry points) are tagged [stable]. That is accurate for the param itself, but the function the param lives on is sometimes [experimental] (read_geotiff_gpu). The current convention reads correctly (param tier = function tier), but a one-line note per module that "param-level tiers are bounded by the function-level tier" would head off confusion on the GPU paths.

What looks good

• Every public entry point has a consistent [tier] marker on every parameter. A small import script confirms all seven functions carry at least one marker, the release-contract docs path, and the epic reference.
• The "Out of scope for this release" bullet on open_geotiff / to_geotiff names the items the epic calls out (full GDAL VRT parity, warped VRTs, rotated/sheared write support). The release notes can lean on that language directly.
• The opt-in kwargs are named inline on each experimental / internal-only path (allow_experimental_codecs, allow_internal_only_jpeg, gpu=, chunks=).
• No runtime change. test_compression_docstring_1644, test_supported_features_tiers_2137, test_release_gate_2321 still pass.

Checklist

• Algorithm matches reference / paper -- no algorithmic change.
• All implemented backends produce consistent results -- no runtime change.
• NaN handling is correct -- no runtime change.
• Edge cases are covered by tests -- existing coverage applies.
• Dask chunk boundaries handled correctly -- no runtime change.
• No premature materialization or unnecessary copies -- no runtime change.
• Benchmark exists or is not needed -- not applicable.
• [N/A] README feature matrix updated -- not needed for docstring-only PR.
• Docstrings present and accurate.

[brendancol]

Follow-up review: Align public GeoTIFF docstrings with epic #2340 release contract

All three suggestions and all three nits from the first review pass are applied in commit a89ea66:

• open_geotiff source param now tiers the io.BytesIO case explicitly as advanced (eager numpy path only).
• open_geotiff release-contract header now states the JPEG-in-TIFF asymmetry: read is best-effort with no parity claim, write is internal-only.
• read_geotiff_gpu deprecated gpu alias is now [experimental] to match the function tier.
• to_geotiff streaming_buffer_bytes notes the no-op behaviour for numpy / CuPy / COG paths.
• Internal _vrt.read_vrt / _vrt.write_vrt open with "Do not call this symbol directly from external code."
• open_geotiff and to_geotiff get a one-line note that per-parameter tier markers are bounded by the function-level surface.

Blockers

None.

Suggestions

None remaining.

Nits

None remaining.

Tests

test_compression_docstring_1644, test_supported_features_tiers_2137, test_release_gate_2321 still pass after the follow-up commit (31 passed, 1 xpassed). No runtime change.

Ready for merge once CI is green and a maintainer reviews.