docs: clarify exception phpdoc

src/JsonMapper/Exception/CollectionMappingException.php

@@ -18,6 +18,10 @@
  */
 final class CollectionMappingException extends MappingException
 {
+    /**
+     * @param string $path       Path to the collection that failed to map.
+     * @param string $actualType Type reported for the value that was expected to be iterable.
+     */
     public function __construct(string $path, private readonly string $actualType)
     {
         parent::__construct(
@@ -26,6 +30,14 @@ public function __construct(string $path, private readonly string $actualType)
         );
     }
 
+    /**
+     * Returns the detected type of the value that could not be treated as iterable.
+     *
+     * Callers can surface the type to API consumers to explain why the mapper refused
+     * to process the collection.
+     *
+     * @return string Type information describing the non-iterable value.
+     */
     public function getActualType(): string
     {
         return $this->actualType;

src/JsonMapper/Exception/MappingException.php

@@ -19,6 +19,12 @@
  */
 abstract class MappingException extends RuntimeException
 {
+    /**
+     * @param string $message   Human readable description of the failure scenario.
+     * @param string $path      JSON pointer or dotted path identifying the failing value.
+     * @param int $code         Optional error code to bubble up to the caller.
+     * @param Throwable|null $previous Underlying cause, if the exception wraps another failure.
+     */
     public function __construct(
         string $message,
         private readonly string $path,
@@ -28,6 +34,14 @@ public function __construct(
         parent::__construct($message, $code, $previous);
     }
 
+    /**
+     * Returns the JSON path pointing to the value that could not be mapped.
+     *
+     * Callers can use the path to inform end users about the exact location of the
+     * mapping problem or to log structured diagnostics.
+     *
+     * @return string JSON pointer or dotted path describing the failing location.
+     */
     public function getPath(): string
     {
         return $this->path;

src/JsonMapper/Exception/MissingPropertyException.php

@@ -18,6 +18,11 @@
  */
 final class MissingPropertyException extends MappingException
 {
+    /**
+     * @param string $path         Path indicating where the missing property should have been present.
+     * @param string $propertyName Name of the required property defined on the PHP target.
+     * @param class-string $className Fully qualified name of the DTO or object declaring the property.
+     */
     public function __construct(
         string $path,
         private readonly string $propertyName,
@@ -30,13 +35,24 @@ public function __construct(
         );
     }
 
+    /**
+     * Returns the required property name that could not be resolved from the JSON input.
+     *
+     * Use this to inform API clients about the field they need to provide.
+     *
+     * @return string Name of the missing property.
+     */
     public function getPropertyName(): string
     {
         return $this->propertyName;
     }
 
     /**
-     * @return class-string
+     * Provides the class in which the missing property is declared.
+     *
+     * Consumers may use the information to scope the validation error when working with nested DTOs.
+     *
+     * @return class-string Fully qualified class name declaring the missing property.
      */
     public function getClassName(): string
     {

src/JsonMapper/Exception/ReadonlyPropertyException.php

@@ -18,6 +18,11 @@
  */
 final class ReadonlyPropertyException extends MappingException
 {
+    /**
+     * @param string $path      Path pointing to the JSON field that tried to set the readonly property.
+     * @param string $property  Name of the property that cannot be written.
+     * @param string $className Fully qualified class declaring the readonly property.
+     */
     public function __construct(string $path, string $property, string $className)
     {
         parent::__construct(

src/JsonMapper/Exception/TypeMismatchException.php

@@ -18,6 +18,11 @@
  */
 final class TypeMismatchException extends MappingException
 {
+    /**
+     * @param string $path         Path to the offending value inside the JSON payload.
+     * @param string $expectedType Type declared on the PHP target (FQCN or scalar type name).
+     * @param string $actualType   Detected type of the JSON value that failed conversion.
+     */
     public function __construct(
         string $path,
         private readonly string $expectedType,
@@ -29,11 +34,27 @@ public function __construct(
         );
     }
 
+    /**
+     * Returns the PHP type the mapper attempted to hydrate.
+     *
+     * Callers may use the information to build error messages that mirror the
+     * DTO or property contract.
+     *
+     * @return string Declared PHP type expected for the JSON value.
+     */
     public function getExpectedType(): string
     {
         return $this->expectedType;
     }
 
+    /**
+     * Returns the actual type the mapper observed in the JSON payload.
+     *
+     * Consumers can combine the value with {@see getExpectedType()} to explain
+     * why the assignment failed.
+     *
+     * @return string Type reported for the source value.
+     */
     public function getActualType(): string
     {
         return $this->actualType;

src/JsonMapper/Exception/UnknownPropertyException.php

@@ -18,6 +18,11 @@
  */
 final class UnknownPropertyException extends MappingException
 {
+    /**
+     * @param string $path         Path to the JSON value that references the unknown property.
+     * @param string $propertyName Name of the property that does not exist on the PHP target.
+     * @param class-string $className Fully qualified name of the object that lacks the property.
+     */
     public function __construct(
         string $path,
         private readonly string $propertyName,
@@ -30,13 +35,25 @@ public function __construct(
         );
     }
 
+    /**
+     * Returns the unknown property name as provided by the JSON payload.
+     *
+     * Callers can expose the value in validation errors so clients can remove
+     * unsupported fields.
+     *
+     * @return string Property name that could not be mapped.
+     */
     public function getPropertyName(): string
     {
         return $this->propertyName;
     }
 
     /**
-     * @return class-string
+     * Provides the class for which the property is unknown.
+     *
+     * Consumers may use this to highlight which DTO rejected the incoming property.
+     *
+     * @return class-string Fully qualified class name without the referenced property.
      */
     public function getClassName(): string
     {