docs: clarify phpdoc for collection resolvers

src/JsonMapper/Collection/CollectionDocBlockTypeResolver.php

@@ -36,6 +36,11 @@ final class CollectionDocBlockTypeResolver
 {
     private DocBlockFactoryInterface $docBlockFactory;
 
+    /**
+     * @param DocBlockFactoryInterface|null $docBlockFactory Optional docblock factory used to parse collection annotations.
+     * @param ContextFactory $contextFactory Factory for building type resolution contexts for reflected classes.
+     * @param PhpDocTypeHelper $phpDocTypeHelper Helper translating DocBlock types into Symfony TypeInfo representations.
+     */
     public function __construct(
         ?DocBlockFactoryInterface $docBlockFactory = null,
         private readonly ContextFactory $contextFactory = new ContextFactory(),
@@ -56,9 +61,9 @@ public function __construct(
     /**
      * Attempts to resolve a {@see CollectionType} from the collection class PHPDoc.
      *
-     * @param class-string $collectionClassName
+     * @param class-string $collectionClassName Fully qualified class name of the collection wrapper to inspect.
      *
-     * @return CollectionType<CollectionWrappedType|GenericType<CollectionWrappedType>>|null
+     * @return CollectionType<CollectionWrappedType|GenericType<CollectionWrappedType>>|null Resolved collection metadata or null when no matching PHPDoc is available.
      */
     public function resolve(string $collectionClassName): ?CollectionType
     {

src/JsonMapper/Collection/CollectionFactory.php

@@ -54,7 +54,11 @@ public function __construct(
     /**
      * Converts the provided iterable JSON structure to a PHP array.
      *
-     * @return array<array-key, mixed>|null
+     * @param mixed $json Raw JSON data representing the collection to hydrate.
+     * @param Type $valueType Type descriptor for individual collection entries.
+     * @param MappingContext $context Active mapping context providing path and strictness information.
+     *
+     * @return array<array-key, mixed>|null Normalised collection data or null when conversion fails.
      */
     public function mapIterable(mixed $json, Type $valueType, MappingContext $context): ?array
     {
@@ -96,9 +100,11 @@ public function mapIterable(mixed $json, Type $valueType, MappingContext $contex
     /**
      * Builds a collection based on the specified collection type description.
      *
-     * @param CollectionType<CollectionWrappedType|GenericType<CollectionWrappedType>> $type
+     * @param CollectionType<CollectionWrappedType|GenericType<CollectionWrappedType>> $type Resolved collection metadata from docblocks or attributes.
+     * @param mixed $json Raw JSON payload containing the collection values.
+     * @param MappingContext $context Mapping context controlling strict mode and error tracking.
      *
-     * @return object|array<array-key, mixed>|null
+     * @return object|array<array-key, mixed>|null Instantiated collection wrapper or the normalised array values.
      */
     public function fromCollectionType(CollectionType $type, mixed $json, MappingContext $context): array|object|null
     {

src/JsonMapper/Collection/CollectionFactoryInterface.php

@@ -32,18 +32,22 @@ interface CollectionFactoryInterface
     /**
      * Converts the provided iterable JSON structure to a PHP array.
      *
-     * @param Type $valueType The type description for the collection values.
+     * @param mixed $json Raw JSON data representing the iterable input to normalise.
+     * @param Type $valueType Type description for the collection values.
+     * @param MappingContext $context Active mapping context carrying strictness and error reporting configuration.
      *
-     * @return array<TKey, TValue>|null
+     * @return array<TKey, TValue>|null Normalised array representation or null when conversion fails.
      */
     public function mapIterable(mixed $json, Type $valueType, MappingContext $context): ?array;
 
     /**
      * Builds a collection based on the specified collection type description.
      *
-     * @param CollectionType<CollectionWrappedType|GenericType<CollectionWrappedType>> $type The collection type metadata extracted from PHPStan/Psalm annotations.
+     * @param CollectionType<CollectionWrappedType|GenericType<CollectionWrappedType>> $type Resolved collection metadata from PHPDoc or attributes.
+     * @param mixed $json Raw JSON payload containing the collection values.
+     * @param MappingContext $context Mapping context controlling strict mode and error recording.
      *
-     * @return array<TKey, TValue>|object|null
+     * @return array<TKey, TValue>|object|null Instantiated collection wrapper or the normalised array values.
      */
     public function fromCollectionType(CollectionType $type, mixed $json, MappingContext $context): mixed;
 }

src/JsonMapper/Resolver/ClassResolver.php

@@ -36,7 +36,7 @@ final class ClassResolver
     private array $classMap;
 
     /**
-     * @param array<class-string, class-string|Closure(mixed):class-string|Closure(mixed, MappingContext):class-string> $classMap
+     * @param array<class-string, class-string|Closure(mixed):class-string|Closure(mixed, MappingContext):class-string> $classMap Map of base class names to explicit targets or resolver callbacks.
      *
      * @phpstan-param array<class-string, class-string|Closure(mixed):class-string|Closure(mixed, MappingContext):class-string> $classMap
      */
@@ -48,8 +48,8 @@ public function __construct(array $classMap = [])
     /**
      * Adds a custom resolution rule.
      *
-     * @param class-string                                                            $className
-     * @param Closure(mixed):class-string|Closure(mixed, MappingContext):class-string $resolver
+     * @param class-string $className Base class or interface the resolver handles.
+     * @param Closure(mixed):class-string|Closure(mixed, MappingContext):class-string $resolver Callback returning a concrete class based on the JSON payload and optional mapping context.
      *
      * @phpstan-param class-string $className
      * @phpstan-param Closure(mixed):class-string|Closure(mixed, MappingContext):class-string $resolver
@@ -63,11 +63,11 @@ public function add(string $className, Closure $resolver): void
     /**
      * Resolves the class name for the provided JSON payload.
      *
-     * @param class-string   $className
-     * @param mixed          $json
-     * @param MappingContext $context
+     * @param class-string $className Base class name configured in the resolver map.
+     * @param mixed $json Raw JSON fragment inspected to determine the target class.
+     * @param MappingContext $context Mapping context passed to resolution callbacks when required.
      *
-     * @return class-string
+     * @return class-string Fully-qualified class name that should be instantiated for the payload.
      */
     public function resolve(string $className, mixed $json, MappingContext $context): string
     {