Skip to content

proximity/allocation/direction docstrings drifted from the implementation #3091

@brendancol

Description

@brendancol

Describe the bug

Three docstring problems in xrspatial/proximity.py, all user-facing:

  1. All three public functions claim "support NumPy backed, and Dask with NumPy backed xarray DataArray" only. The module dispatches to cupy and dask+cupy backends as well (_process_cupy, _process_dask_cupy), both covered by tests. The same docstrings even contradict themselves: the tie-breaking paragraphs in allocation and direction say the policy "is identical across all backends (numpy, cupy, dask+numpy, dask+cupy)".

  2. direction() opens with a leftover line from a slope/aspect docstring: "Calculates, for all cells in the array, the downward slope direction". The function computes direction to the nearest target, not slope. The next sentence also has a doubled "the the".

  3. The allocation example shows output without a dtype, which reads as float64. The function returns float32 (the numpy backend routes allocation through the brute-force kernel, which allocates float32). The proximity and direction examples both print dtype=float32; allocation should too. The stale comment above the result wrapper ("convert to have same type as of input @raster") describes behavior that does not exist.

Expected behavior

Docstrings state the actual backend support (numpy, cupy, dask+numpy, dask+cupy), direction() describes what it computes, and the allocation example matches real output.

Additional context

Found by the api-consistency sweep against the proximity module. Docs-only change, no behavior edits.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentationseverity:mediumSweep finding: MEDIUMsweep-api-consistencyFound by /sweep-api-consistency

    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