From 1f0423847a8d6a4d46b0ffb4a33f0faeb42ccbde Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Tue, 31 Dec 2024 14:51:04 +0000
Subject: [PATCH] Improve docstrings of zarr.api.synchronous

---
 src/zarr/api/synchronous.py | 33 ++++++++++++++++-----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py
index cd1ef8b38d..cfe3450ccd 100644
--- a/src/zarr/api/synchronous.py
+++ b/src/zarr/api/synchronous.py
@@ -145,7 +145,7 @@ def open(
     storage_options: dict[str, Any] | None = None,
     **kwargs: Any,  # TODO: type kwargs as valid args to async_api.open
 ) -> Array | Group:
-    """Convenience function to open a group or array using file-mode-like semantics.
+    """Open a group or array using file-mode-like semantics.
 
     Parameters
     ----------
@@ -206,7 +206,7 @@ def save(
     path: str | None = None,
     **kwargs: Any,  # TODO: type kwargs as valid args to async_api.save
 ) -> None:
-    """Convenience function to save an array or group of arrays to the local file system.
+    """Save an array or group of arrays to the local file system.
 
     Parameters
     ----------
@@ -239,8 +239,9 @@ def save_array(
     storage_options: dict[str, Any] | None = None,
     **kwargs: Any,  # TODO: type kwargs as valid args to async_api.save_array
 ) -> None:
-    """Convenience function to save a NumPy array to the local file system, following a
-    similar API to the NumPy save() function.
+    """Save a NumPy array to the local file system.
+
+    Follows a similar API to the NumPy save() function.
 
     Parameters
     ----------
@@ -280,8 +281,9 @@ def save_group(
     storage_options: dict[str, Any] | None = None,
     **kwargs: NDArrayLike,
 ) -> None:
-    """Convenience function to save several NumPy arrays to the local file system, following a
-    similar API to the NumPy savez()/savez_compressed() functions.
+    """Save several NumPy arrays to the local file system.
+
+    Follows a similar API to the NumPy savez()/savez_compressed() functions.
 
     Parameters
     ----------
@@ -703,7 +705,7 @@ def empty(shape: ChunkCoords, **kwargs: Any) -> Array:
 # 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 `a`.
+    """Create an empty array like another array.
 
     Parameters
     ----------
@@ -722,8 +724,7 @@ def empty_like(a: ArrayLike, **kwargs: Any) -> Array:
 
 # TODO: add type annotations for kwargs and fill_value
 def full(shape: ChunkCoords, fill_value: Any, **kwargs: Any) -> Array:
-    """Create an array, with `fill_value` being used as the default value for
-    uninitialized portions of the array.
+    """Create an array with a default fill value.
 
     Parameters
     ----------
@@ -745,7 +746,7 @@ def full(shape: ChunkCoords, fill_value: Any, **kwargs: Any) -> Array:
 # TODO: move ArrayLike to common module
 # TODO: add type annotations for kwargs
 def full_like(a: ArrayLike, **kwargs: Any) -> Array:
-    """Create a filled array like `a`.
+    """Create a filled array like another array.
 
     Parameters
     ----------
@@ -764,8 +765,7 @@ def full_like(a: ArrayLike, **kwargs: Any) -> Array:
 
 # TODO: add type annotations for kwargs
 def ones(shape: ChunkCoords, **kwargs: Any) -> Array:
-    """Create an array, with one being used as the default value for
-    uninitialized portions of the array.
+    """Create an array with a fill value of one.
 
     Parameters
     ----------
@@ -784,7 +784,7 @@ def ones(shape: ChunkCoords, **kwargs: Any) -> Array:
 
 # TODO: add type annotations for kwargs
 def ones_like(a: ArrayLike, **kwargs: Any) -> Array:
-    """Create an array of ones like `a`.
+    """Create an array of ones like another array.
 
     Parameters
     ----------
@@ -846,7 +846,7 @@ def open_array(
 
 # TODO: add type annotations for kwargs
 def open_like(a: ArrayLike, path: str, **kwargs: Any) -> Array:
-    """Open a persistent array like `a`.
+    """Open a persistent array like another array.
 
     Parameters
     ----------
@@ -867,8 +867,7 @@ def open_like(a: ArrayLike, path: str, **kwargs: Any) -> Array:
 
 # TODO: add type annotations for kwargs
 def zeros(shape: ChunkCoords, **kwargs: Any) -> Array:
-    """Create an array, with zero being used as the default value for
-    uninitialized portions of the array.
+    """Create an array with a fill value of zero.
 
     Parameters
     ----------
@@ -887,7 +886,7 @@ def zeros(shape: ChunkCoords, **kwargs: Any) -> Array:
 
 # TODO: add type annotations for kwargs
 def zeros_like(a: ArrayLike, **kwargs: Any) -> Array:
-    """Create an array of zeros like `a`.
+    """Create an array of zeros like another array.
 
     Parameters
     ----------