docs(flood): add missing reference entries, examples, and backend notes (#3502)

* docs(flood): add missing reference entries, examples, and backend notes

Three public flood functions (vegetation_roughness, vegetation_curve_number,
flood_depth_vegetation) were exported but listed in no autosummary block, so
they were absent from the rendered API reference. Add them to
docs/source/reference/flood.rst.

None of the seven public functions had an Examples section or stated which
array backends they support. Add a runnable example and a backend note to each
docstring, matching the convention used elsewhere in xrspatial. Document NaN
propagation for curve_number_runoff and travel_time, which previously omitted it.

Documentation only; no behavior changes. Examples were executed against all
backends available on the build host.

* chore(sweep): record flood doc-sweep state (PR #3502)

Author: brendancol

.claude/sweep-documentation-state.csv

@@ -1,4 +1,5 @@
 module,last_inspected,issue,severity_max,categories_found,notes,doc_coverage
+flood,2026-06-25,,HIGH,1;4;5,"Cat4 HIGH: vegetation_roughness, vegetation_curve_number, flood_depth_vegetation public but absent from reference/flood.rst; Cat1 MEDIUM: no Examples on any of 7 public funcs; Cat5 MEDIUM: backend support undocumented (all 4 backends) + NaN propagation undocumented for curve_number_runoff/travel_time. Fixed in deep-sweep-documentation-flood-2026-06-25: added 3 rst entries, Examples+backend Notes to all 7 funcs (examples executed OK on CUDA host), NaN notes. PR #3502 opened with the fix; gh issue create blocked by auto-mode classifier so no issue number.",7/7
 classify,2026-06-25,3506,MEDIUM,1;3,"Cat3: reclassify (numpy/dask/cupy blocks) + equal_interval example outputs were stale/wrong, binary used np.nan in array repr; corrected to actual output (tests confirm code is correct). Cat1: added missing Examples to std_mean, head_tail_breaks, percentiles, maximum_breaks, box_plot. Fixed in deep-sweep-documentation-classify-2026-06-25 (PR for #3506). Cat2 natural_breaks num_sample-None omission already tracked in #3501 (left alone). All 10 public funcs listed in reference/classification.rst (no Cat4 gap). CUDA available: ran numpy examples; cupy/dask reprs reviewed statically.",10/10
 geotiff,2026-06-25,,MEDIUM,1,"to_geotiff (public write entry point) had Parameters/Returns/Raises but no Examples section while open_geotiff does (Cat1 MEDIUM); added Examples block (plain GeoTIFF, cog=True, .vrt mosaic) modeled on open_geotiff; fixed on deep-sweep-documentation-geotiff-2026-06-25; repo issues disabled so no issue number. Cat2/3/4/5 clean: open_geotiff/to_geotiff signature-docstring parity locked by parity/test_signature_contract.py + write/test_bigtiff.py + test_polish.py; both funcs in autosummary in reference/geotiff.rst; reference page mirrors SUPPORTED_FEATURES tiers (tier-parity gate); CUDA available, all docstring examples are +SKIP illustrative only",2/2
 fire,2026-06-25,,MEDIUM,1;5,"all 7 public funcs (dnbr, rdnbr, burn_severity_class, fireline_intensity, flame_length, rate_of_spread, kbdi) lacked Examples section (Cat1 MEDIUM) and backend-support note (Cat5 MEDIUM); fixed in deep-sweep-documentation-fire-2026-06-25-01; repo issues disabled so no issue number; examples run and outputs match numpy backend; all 7 listed in reference/fire.rst; no Cat2/Cat3/Cat4 issues",7/7

docs/source/reference/flood.rst

@@ -31,3 +31,24 @@ Travel Time
     :toctree: _autosummary
 
     xrspatial.flood.travel_time
+
+Vegetation Roughness
+====================
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.flood.vegetation_roughness
+
+Vegetation Curve Number
+=======================
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.flood.vegetation_curve_number
+
+Flood Depth Vegetation
+======================
+.. autosummary::
+    :toctree: _autosummary
+
+    xrspatial.flood.flood_depth_vegetation

xrspatial/flood.py

@@ -151,6 +151,22 @@ def flood_depth(
     xarray.DataArray
         2D float64 grid of flood depths.  ``NaN`` where not inundated
         or where the input is ``NaN``.
+
+    Notes
+    -----
+    Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed
+    xarray DataArrays.
+
+    Examples
+    --------
+    .. sourcecode:: python
+
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xrspatial import flood_depth
+        >>> hand = xr.DataArray(
+        ...     np.array([[0.0, 2.0], [5.0, 10.0]]), dims=['y', 'x'])
+        >>> depth = flood_depth(hand, water_level=5.0)
     """
     _validate_raster(hand_agg, func_name='flood_depth', name='hand_agg')
     if not isinstance(water_level, (int, float)):
@@ -239,6 +255,22 @@ def inundation(
     -------
     xarray.DataArray
         2D float64 binary mask.
+
+    Notes
+    -----
+    Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed
+    xarray DataArrays.
+
+    Examples
+    --------
+    .. sourcecode:: python
+
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xrspatial import inundation
+        >>> hand = xr.DataArray(
+        ...     np.array([[0.0, 2.0], [5.0, 10.0]]), dims=['y', 'x'])
+        >>> mask = inundation(hand, water_level=5.0)
     """
     _validate_raster(hand_agg, func_name='inundation', name='hand_agg')
     if not isinstance(water_level, (int, float)):
@@ -330,6 +362,23 @@ def curve_number_runoff(
     -------
     xarray.DataArray
         2D float64 runoff depth in millimetres.
+
+    Notes
+    -----
+    Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed
+    xarray DataArrays.  ``NaN`` in ``rainfall`` or ``curve_number``
+    propagates to ``NaN`` in the output.
+
+    Examples
+    --------
+    .. sourcecode:: python
+
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xrspatial import curve_number_runoff
+        >>> rainfall = xr.DataArray(
+        ...     np.array([[10.0, 50.0], [100.0, 150.0]]), dims=['y', 'x'])
+        >>> runoff = curve_number_runoff(rainfall, curve_number=80.0)
     """
     _validate_raster(rainfall, func_name='curve_number_runoff',
                      name='rainfall')
@@ -450,6 +499,25 @@ def travel_time(
         2D float64 travel time grid (same time units as flow_length
         distance units and velocity units, typically seconds when
         flow_length is in metres).
+
+    Notes
+    -----
+    Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed
+    xarray DataArrays.  ``NaN`` in ``flow_length_agg`` or ``slope_agg``
+    propagates to ``NaN`` in the output.
+
+    Examples
+    --------
+    .. sourcecode:: python
+
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xrspatial import travel_time
+        >>> flow_length = xr.DataArray(
+        ...     np.array([[100.0, 200.0]]), dims=['y', 'x'])
+        >>> slope = xr.DataArray(
+        ...     np.array([[10.0, 45.0]]), dims=['y', 'x'])
+        >>> tt = travel_time(flow_length, slope, mannings_n=0.03)
     """
     _validate_raster(flow_length_agg, func_name='travel_time',
                      name='flow_length_agg')
@@ -573,6 +641,23 @@ def vegetation_roughness(
     xarray.DataArray
         2D float64 Manning's n raster.  Unrecognized NLCD codes and
         NaN inputs map to NaN.
+
+    Notes
+    -----
+    Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed
+    xarray DataArrays.
+
+    Examples
+    --------
+    .. sourcecode:: python
+
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xrspatial import vegetation_roughness
+        >>> nlcd = xr.DataArray(
+        ...     np.array([[41, 71], [11, 82]], dtype=np.int32),
+        ...     dims=['y', 'x'])
+        >>> roughness = vegetation_roughness(nlcd, mode='nlcd')
     """
     _validate_raster(vegetation_agg, func_name='vegetation_roughness',
                      name='vegetation_agg')
@@ -736,6 +821,24 @@ def vegetation_curve_number(
     xarray.DataArray
         2D float64 curve number raster.  Unknown ``(code, group)``
         pairs and NaN inputs map to NaN.
+
+    Notes
+    -----
+    Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed
+    xarray DataArrays.
+
+    Examples
+    --------
+    .. sourcecode:: python
+
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xrspatial import vegetation_curve_number
+        >>> landcover = xr.DataArray(
+        ...     np.array([[41, 24]], dtype=np.int32), dims=['y', 'x'])
+        >>> soil_group = xr.DataArray(
+        ...     np.array([[1, 4]], dtype=np.int32), dims=['y', 'x'])
+        >>> cn = vegetation_curve_number(landcover, soil_group)
     """
     _validate_raster(landcover_agg, func_name='vegetation_curve_number',
                      name='landcover_agg')
@@ -883,6 +986,25 @@ def flood_depth_vegetation(
     xarray.DataArray
         2D float64 flood depth grid.  NaN where not inundated or
         where inputs are NaN.
+
+    Notes
+    -----
+    Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed
+    xarray DataArrays.
+
+    Examples
+    --------
+    .. sourcecode:: python
+
+        >>> import numpy as np
+        >>> import xarray as xr
+        >>> from xrspatial import flood_depth_vegetation
+        >>> hand = xr.DataArray(
+        ...     np.array([[0.0, 1.0]]), dims=['y', 'x'])
+        >>> slope = xr.DataArray(
+        ...     np.array([[10.0, 10.0]]), dims=['y', 'x'])
+        >>> depth = flood_depth_vegetation(
+        ...     hand, slope, mannings_n=0.10, unit_discharge=0.5)
     """
     _validate_raster(hand_agg, func_name='flood_depth_vegetation',
                      name='hand_agg')