harmonize docstrings

Author: d-v-b

src/zarr/core/dtype/npy/bool.py

@@ -21,8 +21,10 @@
 @dataclass(frozen=True, kw_only=True, slots=True)
 class Bool(ZDType[np.dtypes.BoolDType, np.bool_], HasItemSize):
     """
-    A Zarr data type for arrays containing booleans. Wraps the NumPy
-    ``np.dtypes.BoolDType`` data type. Scalars for this data type are instances of ``np.bool_``.
+    A Zarr data type for arrays containing booleans.
+
+    Wraps the NumPy ``np.dtypes.BoolDType`` data type. Scalars for this data type are instances of
+    ``np.bool_``.
 
     Attributes
     ----------

src/zarr/core/dtype/npy/bytes.py

@@ -35,8 +35,10 @@ class FixedLengthBytesConfig(TypedDict):
 @dataclass(frozen=True, kw_only=True)
 class NullTerminatedBytes(ZDType[np.dtypes.BytesDType[int], np.bytes_], HasLength, HasItemSize):
     """
-    A Zarr data type for arrays containing null-terminated bytes. Wraps the NumPy
-    ``np.dtypes.BytesDType`` data type. Scalars for this data type are instances of ``np.bytes_``.
+    A Zarr data type for arrays containing fixed-length null-terminated byte sequences.
+
+    Wraps the NumPy ``np.dtypes.BytesDType`` data type. Scalars for this data type are instances of
+    ``np.bytes_``.
 
     This data type is parametrized by an integral length which specifies size in bytes of each
     scalar. Because this data type uses null-terminated semantics, indexing into
@@ -158,15 +160,6 @@ def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[NullTerminatedBytesJSONV3]
         """
         Check that the input is a valid representation of NullTerminatedBytes in Zarr V3.
 
-        The input must be a mapping with the following structure:
-
-        {
-            "name": "null_terminated_bytes",
-            "configuration": {
-                "length_bytes": <int>
-            }
-        }
-
         Parameters
         ----------
         data : DTypeJSON
@@ -256,19 +249,7 @@ def to_json(
         self, zarr_format: ZarrFormat
     ) -> DTypeConfig_V2[str, None] | NullTerminatedBytesJSONV3:
         """
-        Generate a JSON representation of NullTerminatedBytes.
-
-        If zarr_format is 2, the return value will be a dictionary with the form
-        {
-            "name": "|S<self.length>",
-            "object_codec_id": None
-        }
-
-        If zarr_format is 3, the resulting JSON will be a dictionary with the form
-        {
-            "name": "null_terminated_bytes",
-            "configuration": {"length_bytes": self.length}
-        }
+        Generate a JSON representation of this data type.
 
         Parameters
         ----------
@@ -440,13 +421,10 @@ def item_size(self) -> int:
 
 @dataclass(frozen=True, kw_only=True)
 class RawBytes(ZDType[np.dtypes.VoidDType[int], np.void], HasLength, HasItemSize):
-    # np.dtypes.VoidDType is specified in an odd way in NumPy
-    # it cannot be used to create instances of the dtype
-    # so we have to tell mypy to ignore this here
-
     """
-    A Zarr data type for arrays containing raw bytes. Wraps the NumPy ``void`` data type.
-    Scalars for this data type are instances of ``np.void``.
+    A Zarr data type for arrays containing fixed-length sequences of raw bytes.
+
+    Wraps the NumPy ``void`` data type. Scalars for this data type are instances of ``np.void``.
 
     This data type is parametrized by an integral length which specifies size in bytes of each
     scalar belonging to this data type.
@@ -491,6 +469,9 @@ class does not support structured data types.
 
     """
 
+    # np.dtypes.VoidDType is specified in an odd way in NumPy
+    # it cannot be used to create instances of the dtype
+    # so we have to tell mypy to ignore this here
     dtype_cls = np.dtypes.VoidDType  # type: ignore[assignment]
     _zarr_v3_name: ClassVar[Literal["raw_bytes"]] = "raw_bytes"
 
@@ -694,19 +675,7 @@ def to_json(self, zarr_format: Literal[3]) -> RawBytesJSONV3: ...
 
     def to_json(self, zarr_format: ZarrFormat) -> DTypeConfig_V2[str, None] | RawBytesJSONV3:
         """
-        Generate a JSON representation of RawBytes.
-
-        If zarr_format is 2, the return value will be a dictionary with the form
-        {
-            "name": "|V<self.length>",
-            "object_codec_id": None
-        }
-
-        If zarr_format is 3, the resulting JSON will be a dictionary with the form
-        {
-            "name": "raw_bytes",
-            "configuration": {"length_bytes": self.length}
-        }
+        Generate a JSON representation of this data type.
 
         Parameters
         ----------
@@ -874,8 +843,9 @@ def item_size(self) -> int:
 @dataclass(frozen=True, kw_only=True)
 class VariableLengthBytes(ZDType[np.dtypes.ObjectDType, bytes], HasObjectCodec):
     """
-    A Zarr data type for arrays containing variable-length bytes. Wraps the NumPy
-    "object" data type. Scalars for this data type are instances of plain python bytes.
+    A Zarr data type for arrays containing variable-length sequences of bytes.
+
+    Wraps the NumPy "object" data type. Scalars for this data type are instances of ``bytes``.
 
     Attributes
     ----------

src/zarr/core/dtype/npy/int.py

@@ -256,7 +256,7 @@ def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
 @dataclass(frozen=True, kw_only=True)
 class Int8(BaseInt[np.dtypes.Int8DType, np.int8]):
     """
-    A Zarr data type for 8-bit signed integers.
+    A Zarr data type for arrays containing 8-bit signed integers.
 
     Wraps the NumPy ``np.dtypes.Int8DType`` data type. Scalars for this data type are
     instances of ``np.int8``.
@@ -555,8 +555,10 @@ def item_size(self) -> int:
 @dataclass(frozen=True, kw_only=True)
 class Int16(BaseInt[np.dtypes.Int16DType, np.int16], HasEndianness):
     """
-    A Zarr data type for arrays containing 16-bit signed integers. Wraps the NumPy
-    np.dtypes.Int16DType data type. Scalars for this data type are instances np.int16.
+    A Zarr data type for arrays containing 16-bit signed integers.
+
+    Wraps the NumPy ``np.dtypes.Int16DType`` data type. Scalars for this data type are instances of
+    ``np.int16``.
 
     Attributes
     ----------
@@ -675,16 +677,6 @@ def to_json(
         """
         Serialize this ZDType to v2- or v3-flavored JSON
 
-        If the zarr_format is 2, then return a dict like this:
-        .. code-block:: json
-
-        {
-            "name": ">i2" or "<i2",
-            "object_codec_id": None
-        }
-
-        If the zarr_format is 3, then return the string "int16"
-
         Parameters
         ----------
         zarr_format : ZarrFormat
@@ -845,16 +837,6 @@ def to_json(
         """
         Serialize this ZDType to v2- or v3-flavored JSON
 
-        If the zarr_format is 2, then return a dict like this:
-        .. code-block:: json
-
-        {
-            "name": ">u2" or "<u2",
-            "object_codec_id": None
-        }
-
-        If the zarr_format is 3, then return the string "uint16"
-
         Parameters
         ----------
         zarr_format : ZarrFormat
@@ -1015,16 +997,6 @@ def to_json(
         """
         Serialize this ZDType to v2- or v3-flavored JSON
 
-        If the zarr_format is 2, then return a dict like this:
-        .. code-block:: json
-
-        {
-            "name": ">i4" or "<i4",
-            "object_codec_id": None
-        }
-
-        If the zarr_format is 3, then return the string "int32"
-
         Parameters
         ----------
         zarr_format : ZarrFormat
@@ -1377,7 +1349,7 @@ class UInt64(BaseInt[np.dtypes.UInt64DType, np.uint64], HasEndianness):
     """
     A Zarr data type for arrays containing 64-bit unsigned integers.
 
-    This data type wraps the NumPy ``np.dtypes.UInt64DType`` data type. Scalars for this data type
+    Wraps the NumPy ``np.dtypes.UInt64DType`` data type. Scalars for this data type
     are instances of ``np.uint64``.
 
     Attributes

src/zarr/core/dtype/npy/string.py

@@ -62,7 +62,8 @@ class FixedLengthUTF32(
     """
     A Zarr data type for arrays containing fixed-length UTF-32 strings.
 
-    Wraps the NumPy np.dtypes.StrDType data type. Scalars for this data type are instances of np.str_.
+    Wraps the NumPy ``np.dtypes.StrDType`` data type. Scalars for this data type are instances of
+    ``np.str_``.
 
     Attributes
     ----------
@@ -640,8 +641,10 @@ def cast_scalar(self, data: object) -> str:
     @dataclass(frozen=True, kw_only=True)
     class VariableLengthUTF8(UTF8Base[np.dtypes.StringDType]):  # type: ignore[type-var]
         """
-        A Zarr data type for arrays containing variable-length UTF-8 strings. Wraps the
-        NumPy np.dtypes.StringDType data type. Scalars for this data type are Python strings.
+        A Zarr data type for arrays containing variable-length UTF-8 strings.
+
+        Wraps the NumPy ``np.dtypes.StringDType`` data type. Scalars for this data type are instances
+        of ``str``.
 
 
         Attributes
@@ -672,8 +675,10 @@ def to_native_dtype(self) -> np.dtypes.StringDType:
     @dataclass(frozen=True, kw_only=True)
     class VariableLengthUTF8(UTF8Base[np.dtypes.ObjectDType]):  # type: ignore[no-redef]
         """
-        A Zarr data type for arrays containing variable-length UTF-8 strings. Wraps the
-        NumPy np.dtypes.ObjectDType data type. Scalars for this data type are Python strings.
+        A Zarr data type for arrays containing variable-length UTF-8 strings.
+
+        Wraps the NumPy ``np.dtypes.ObjectDType`` data type. Scalars for this data type are instances
+        of ``str``.
 
 
         Attributes