Skip to content

Audit public GeoTIFF docstrings against release contract (epic #2340) #2346

@brendancol

Description

@brendancol

Summary

Audit the docstrings of the seven public GeoTIFF API functions so they match the release contract proposed in epic #2340. Today's docstrings imply more support than the contract promises: full GDAL VRT parity, stable GPU paths, and stable exotic codecs (LERC, JPEG2000, LZ4, JPEG-in-TIFF).

Scope

Tag every parameter and behavior in:

  • open_geotiff
  • read_geotiff_dask
  • read_geotiff_gpu
  • read_vrt
  • to_geotiff
  • write_geotiff_gpu
  • write_vrt

with one of the four tier markers from epic #2340: stable, advanced, experimental, internal-only.

Drop language that implies broader support than the contract. Where a code path is experimental or internal-only, name the opt-in kwarg in the docstring. Cross-reference the release-contract docs page under docs/source/reference/; if that file has not landed yet, use the expected path so the link resolves once PR 2 lands.

Constraints

  • Docstrings only. No runtime behavior changes.
  • Do not touch _attrs.py (PR 1).
  • Do not add tests beyond doctest fixes.
  • Any real correctness issue spotted while reading gets a separate follow-up issue, not a fix in this PR.

Acceptance

  • Every parameter / behavior in each of the seven functions carries a tier marker.
  • No remaining language promises full GDAL VRT parity, warped VRT, stable GPU, or stable LERC/J2K/LZ4/JPEG-in-TIFF.
  • Experimental / internal-only paths name their opt-in kwarg.
  • The release-contract docs page is cross-referenced.

Part of epic #2340. PR 3 of 6.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions