update docstrings

Author: brokkoli71

src/zarr/api/asynchronous.py

@@ -1065,20 +1065,15 @@ async def create(
 async def empty(
     shape: ChunkCoords, **kwargs: Any
 ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
-    """Create an empty array.
+    """Create an empty array with the specified shape. The contents will be filled with the
+    array's fill value or zeros if no fill value is provided.
 
     Parameters
     ----------
     shape : int or tuple of int
         Shape of the empty array.
     **kwargs
         Keyword arguments passed to :func:`zarr.api.asynchronous.create`.
-
-    Notes
-    -----
-    The contents of an empty Zarr array are not defined. On attempting to
-    retrieve data from an empty Zarr array, any values may be returned,
-    and these are not guaranteed to be stable from one access to the next.
     """
 
     return await create(shape=shape, fill_value=None, **kwargs)
@@ -1087,7 +1082,8 @@ async def empty(
 async def empty_like(
     a: ArrayLike, **kwargs: Any
 ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
-    """Create an empty array like `a`.
+    """Create an empty array like `a`. The contents will be filled with the
+    array's fill value or zeros if no fill value is provided.
 
     Parameters
     ----------

src/zarr/api/synchronous.py

@@ -895,7 +895,8 @@ def create_array(
 
 # TODO: add type annotations for kwargs
 def empty(shape: ChunkCoords, **kwargs: Any) -> Array:
-    """Create an empty array.
+    """Create an empty array with the specified shape. The contents will be filled with the
+    array's fill value or zeros if no fill value is provided.
 
     Parameters
     ----------
@@ -908,20 +909,15 @@ def empty(shape: ChunkCoords, **kwargs: Any) -> Array:
     -------
     Array
         The new array.
-
-    Notes
-    -----
-    The contents of an empty Zarr array are not defined. On attempting to
-    retrieve data from an empty Zarr array, any values may be returned,
-    and these are not guaranteed to be stable from one access to the next.
     """
     return Array(sync(async_api.empty(shape, **kwargs)))
 
 
 # TODO: move ArrayLike to common module
 # TODO: add type annotations for kwargs
 def empty_like(a: ArrayLike, **kwargs: Any) -> Array:
-    """Create an empty array like another array.
+    """Create an empty array like another array. The contents will be filled with the
+    array's fill value or zeros if no fill value is provided.
 
     Parameters
     ----------

src/zarr/core/group.py

@@ -1498,7 +1498,8 @@ async def tree(self, expand: bool | None = None, level: int | None = None) -> An
     async def empty(
         self, *, name: str, shape: ChunkCoords, **kwargs: Any
     ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
-        """Create an empty array in this Group.
+        """Create an empty array with the specified shape in this Group. The contents will
+        be filled with the array's fill value or zeros if no fill value is provided.
 
         Parameters
         ----------
@@ -1592,7 +1593,8 @@ async def full(
     async def empty_like(
         self, *, name: str, data: async_api.ArrayLike, **kwargs: Any
     ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
-        """Create an empty sub-array like `data`.
+        """Create an empty sub-array like `data`. The contents will be filled with
+        the array's fill value or zeros if no fill value is provided.
 
         Parameters
         ----------
@@ -2442,7 +2444,8 @@ def require_array(self, name: str, *, shape: ShapeLike, **kwargs: Any) -> Array:
 
     @_deprecate_positional_args
     def empty(self, *, name: str, shape: ChunkCoords, **kwargs: Any) -> Array:
-        """Create an empty array in this Group.
+        """Create an empty array with the specified shape in this Group. The contents will be filled with
+        the array's fill value or zeros if no fill value is provided.
 
         Parameters
         ----------
@@ -2453,11 +2456,6 @@ def empty(self, *, name: str, shape: ChunkCoords, **kwargs: Any) -> Array:
         **kwargs
             Keyword arguments passed to :func:`zarr.api.asynchronous.create`.
 
-        Notes
-        -----
-        The contents of an empty Zarr array are not defined. On attempting to
-        retrieve data from an empty Zarr array, any values may be returned,
-        and these are not guaranteed to be stable from one access to the next.
         """
         return Array(self._sync(self._async_group.empty(name=name, shape=shape, **kwargs)))
 
@@ -2531,7 +2529,8 @@ def full(
 
     @_deprecate_positional_args
     def empty_like(self, *, name: str, data: async_api.ArrayLike, **kwargs: Any) -> Array:
-        """Create an empty sub-array like `data`.
+        """Create an empty sub-array like `data`. The contents will be filled
+        with the array's fill value or zeros if no fill value is provided.
 
         Parameters
         ----------