improve docstrings

Author: d-v-b

src/zarr/codecs/cast_value.py

@@ -142,20 +142,35 @@ class CastValue(ArrayArrayCodec):
     Value-converts array elements to a new data type during encoding,
     and back to the original data type during decoding.
 
-    Requires the ``cast-value-rs`` package for the actual casting logic.
+    Requires the `cast-value-rs` package for the actual casting logic.
 
     Parameters
     ----------
-    data_type : str
-        Target zarr v3 data type name (e.g. "uint8", "float32").
+    data_type : str or ZDType
+        Target zarr v3 data type. Strings are looked up by spec name
+        (e.g. "uint8", "float32"); a `ZDType` instance is used as-is.
     rounding : RoundingMode
-        How to round when exact representation is impossible. Default is "nearest-even".
+        How to round when exact representation is impossible. Default is
+        "nearest-even".
     out_of_range : OutOfRangeMode or None
-        What to do when a value is outside the target's range.
-        None means error. "clamp" clips to range. "wrap" uses modular arithmetic
-        (only valid for integer types).
-    scalar_map : dict or None
-        Explicit mapping from input scalars to output scalars.
+        What to do when a value is outside the target's range. `None` means
+        error; "clamp" clips to range; "wrap" uses modular arithmetic
+        (only valid for integer types). Default is `None`.
+    scalar_map : ScalarMap, ScalarMapJSON, or None
+        Explicit mapping from input scalars to output scalars. Default is
+        `None`.
+
+    Attributes
+    ----------
+    dtype : ZDType
+        Resolved target data type (a `ZDType` instance, regardless of
+        whether the constructor received a string or a `ZDType`).
+    rounding : RoundingMode
+        The rounding mode, as supplied to the constructor.
+    out_of_range : OutOfRangeMode or None
+        The out-of-range behaviour, as supplied to the constructor.
+    scalar_map : ScalarMap or None
+        Parsed scalar map (always normalized to `ScalarMap` form).
 
     References
     ----------

src/zarr/codecs/scale_offset.py

@@ -283,20 +283,32 @@ def _decode(
 class ScaleOffset(ArrayArrayCodec):
     """Scale-offset array-to-array codec.
 
-    Encodes values with ``out = (in - offset) * scale`` and decodes with
-    ``out = (in / scale) + offset``, using the input array's data type semantics.
+    Encodes values with `out = (in - offset) * scale` and decodes with
+    `out = (in / scale) + offset`, using the input array's data type semantics.
     Intermediate or final values that are not representable in that dtype are reported
     as errors (integer overflow, unsigned underflow, non-exact integer division).
 
-    See https://github.com/zarr-developers/zarr-extensions/tree/main/codecs/scale_offset
-    for the codec specification.
-
     Parameters
     ----------
-    offset : float
-        Value subtracted during encoding. Default is 0.
-    scale : float
-        Value multiplied during encoding (after offset subtraction). Default is 1.
+    offset : int, float, or str
+        Value subtracted during encoding. Strings preserve the exact JSON
+        representation when round-tripping metadata. Default is 0.
+    scale : int, float, or str
+        Value multiplied during encoding (after offset subtraction). Strings
+        preserve the exact JSON representation when round-tripping metadata.
+        Default is 1.
+
+    Attributes
+    ----------
+    offset : int, float, or str
+        The offset value, as supplied to the constructor.
+    scale : int, float, or str
+        The scale value, as supplied to the constructor.
+
+    References
+    ----------
+
+    - The `scale_offset` codec spec: https://github.com/zarr-developers/zarr-extensions/tree/main/codecs/scale_offset
     """
 
     is_fixed_size = True