update docstring

TomAugspurger · Oct 21, 2024 · ff0f2c0 · ff0f2c0
1 parent be79e88
commit ff0f2c0
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 0 deletions.
diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
@@ -4342,6 +4342,14 @@ def to_zarr(
             * ``dask.delayed.Delayed`` if compute is False
             * ZarrStore otherwise
 
+        Notes
+        -----
+        There exists a subtlety in interpreting zarr's ``fill_value`` property. For zarr v2 format
+        arrays, ``fill_value`` is *always* interpreted as an invalid value similar to the ``_FillValue`` attribute
+        in CF/netCDF. For Zarr v3 format arrays, only an explicit ``_FillValue`` attribute will be used
+        to mask the data if requested using ``mask_and_scale=True``. See this :ref:`Github issue <https://github.com/pydata/xarray/issues/5475>`_
+        for more.
+
         References
         ----------
         https://zarr.readthedocs.io/

diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
@@ -2561,6 +2561,14 @@ def to_zarr(
             * ``dask.delayed.Delayed`` if compute is False
             * ZarrStore otherwise
 
+        Notes
+        -----
+        There exists a subtlety in interpreting zarr's ``fill_value`` property. For zarr v2 format
+        arrays, ``fill_value`` is *always* interpreted as an invalid value similar to the ``_FillValue`` attribute
+        in CF/netCDF. For Zarr v3 format arrays, only an explicit ``_FillValue`` attribute will be used
+        to mask the data if requested using ``mask_and_scale=True``. See this :ref:`Github issue <https://github.com/pydata/xarray/issues/5475>`_
+        for more.
+
         References
         ----------
         https://zarr.readthedocs.io/