From c070940e1f6c94b658c5e78c22e0d6466ea9591d Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Fri, 3 Jan 2025 01:03:26 +0000
Subject: [PATCH] Improve exception docs (#2624)

---
 src/zarr/errors.py | 38 +++++++++++++++++++++++++-------------
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/src/zarr/errors.py b/src/zarr/errors.py
index 5eb696d935..441cdab9a3 100644
--- a/src/zarr/errors.py
+++ b/src/zarr/errors.py
@@ -1,22 +1,41 @@
 from typing import Any
 
+__all__ = [
+    "BaseZarrError",
+    "ContainsArrayAndGroupError",
+    "ContainsArrayError",
+    "ContainsGroupError",
+    "MetadataValidationError",
+    "NodeTypeValidationError",
+]
+
+
+class BaseZarrError(ValueError):
+    """
+    Base error which all zarr errors are sub-classed from.
+    """
 
-class _BaseZarrError(ValueError):
     _msg = ""
 
     def __init__(self, *args: Any) -> None:
         super().__init__(self._msg.format(*args))
 
 
-class ContainsGroupError(_BaseZarrError):
+class ContainsGroupError(BaseZarrError):
+    """Raised when a group already exists at a certain path."""
+
     _msg = "A group exists in store {!r} at path {!r}."
 
 
-class ContainsArrayError(_BaseZarrError):
+class ContainsArrayError(BaseZarrError):
+    """Raised when an array already exists at a certain path."""
+
     _msg = "An array exists in store {!r} at path {!r}."
 
 
-class ContainsArrayAndGroupError(_BaseZarrError):
+class ContainsArrayAndGroupError(BaseZarrError):
+    """Raised when both array and group metadata are found at the same path."""
+
     _msg = (
         "Array and group metadata documents (.zarray and .zgroup) were both found in store "
         "{!r} at path {!r}. "
@@ -25,8 +44,8 @@ class ContainsArrayAndGroupError(_BaseZarrError):
     )
 
 
-class MetadataValidationError(_BaseZarrError):
-    """An exception raised when the Zarr metadata is invalid in some way"""
+class MetadataValidationError(BaseZarrError):
+    """Raised when the Zarr metadata is invalid in some way"""
 
     _msg = "Invalid value for '{}'. Expected '{}'. Got '{}'."
 
@@ -38,10 +57,3 @@ class NodeTypeValidationError(MetadataValidationError):
     This can be raised when the value is invalid or unexpected given the context,
     for example an 'array' node when we expected a 'group'.
     """
-
-
-__all__ = [
-    "ContainsArrayAndGroupError",
-    "ContainsArrayError",
-    "ContainsGroupError",
-]