Improve documentation of thrown exceptions via Hydrator

src/Hydrator.php

@@ -13,11 +13,18 @@ interface Hydrator
      * @return T
      *
      * @throws ClassNotSupported if the class is not supported or not found.
+     * @throws DenormalizationFailure if any normalizers throw an exception.
+     * @throws TypeMismatch if a TypeError occurs when setting a property value.
+     * @throws HydratorException Any other thrown exceptions should implement HydratorException.
      *
      * @template T of object
      */
     public function hydrate(string $class, array $data): object;
 
-    /** @return array<string, mixed> */
+    /**
+     * @return array<string, mixed>
+     *
+     * @throws HydratorException
+     */
     public function extract(object $object): array;
 }

src/HydratorException.php

@@ -4,6 +4,8 @@
 
 namespace Patchlevel\Hydrator;
 
-interface HydratorException
+use Throwable;
+
+interface HydratorException extends Throwable
 {
 }

src/HydratorWithContext.php

@@ -16,6 +16,9 @@ interface HydratorWithContext extends Hydrator
      * @return T
      *
      * @throws ClassNotSupported if the class is not supported or not found.
+     * @throws DenormalizationFailure if any normalizers throw an exception.
+     * @throws TypeMismatch if a TypeError occurs when setting a property value.
+     * @throws HydratorException Any other thrown exceptions should implement HydratorException.
      *
      * @template T of object
      */
@@ -25,6 +28,8 @@ public function hydrate(string $class, array $data, array $context = []): object
      * @param array<string, mixed> $context
      *
      * @return array<string, mixed>
+     *
+     * @throws HydratorException
      */
     public function extract(object $object, array $context = []): array;
 }

src/MetadataHydrator.php

@@ -62,6 +62,11 @@ public function __construct(
      *
      * @return T
      *
+     * @throws ClassNotSupported if the target class does not exist.
+     * @throws DenormalizationFailure if any normalizers throw an exception.
+     * @throws TypeMismatch if a TypeError occurs when setting a property value.
+     * @throws HydratorException Any other thrown exceptions should implement HydratorException.
+     *
      * @template T of object
      */
     public function hydrate(string $class, array $data, array $context = []): object
@@ -96,6 +101,9 @@ function () use ($metadata, $data, $context): object {
      *
      * @return T
      *
+     * @throws DenormalizationFailure if any normalizers throw an exception.
+     * @throws TypeMismatch if a TypeError occurs when setting a property value.
+     *
      * @template T of object
      */
     private function doHydrate(ClassMetadata $metadata, array $data, array $context = []): object
@@ -179,6 +187,11 @@ private function doHydrate(ClassMetadata $metadata, array $data, array $context
      * @param array<string, mixed> $context
      *
      * @return array<string, mixed>
+     *
+     * @throws CircularReference
+     * @throws NormalizationFailure
+     * @throws NormalizationMissing
+     * @throws ClassNotFound
      */
     public function extract(object $object, array $context = []): array
     {