improved phpDoc

Array::some(), every(), map() are intentionally annotated only for arrays

Author: dg

src/Utils/Arrays.php

@@ -122,10 +122,11 @@ public static function contains(array $array, mixed $value): bool
 
 	/**
 	 * Returns the first item (matching the specified predicate if given). If there is no such item, it returns result of invoking $else or null.
-	 * The $predicate has the signature `function (mixed $value, int|string $key, array $array): bool`.
-	 * @template T
-	 * @param  array<T>  $array
-	 * @return ?T
+	 * @template K of int|string
+	 * @template V
+	 * @param  array<K, V>  $array
+	 * @param  ?callable(V, K, array<K, V>): bool  $predicate
+	 * @return ?V
 	 */
 	public static function first(array $array, ?callable $predicate = null, ?callable $else = null): mixed
 	{
@@ -138,10 +139,11 @@ public static function first(array $array, ?callable $predicate = null, ?callabl
 
 	/**
 	 * Returns the last item (matching the specified predicate if given). If there is no such item, it returns result of invoking $else or null.
-	 * The $predicate has the signature `function (mixed $value, int|string $key, array $array): bool`.
-	 * @template T
-	 * @param  array<T>  $array
-	 * @return ?T
+	 * @template K of int|string
+	 * @template V
+	 * @param  array<K, V>  $array
+	 * @param  ?callable(V, K, array<K, V>): bool  $predicate
+	 * @return ?V
 	 */
 	public static function last(array $array, ?callable $predicate = null, ?callable $else = null): mixed
 	{
@@ -154,7 +156,11 @@ public static function last(array $array, ?callable $predicate = null, ?callable
 
 	/**
 	 * Returns the key of first item (matching the specified predicate if given) or null if there is no such item.
-	 * The $predicate has the signature `function (mixed $value, int|string $key, array $array): bool`.
+	 * @template K of int|string
+	 * @template V
+	 * @param  array<K, V>  $array
+	 * @param  ?callable(V, K, array<K, V>): bool  $predicate
+	 * @return ?K
 	 */
 	public static function firstKey(array $array, ?callable $predicate = null): int|string|null
 	{
@@ -172,7 +178,11 @@ public static function firstKey(array $array, ?callable $predicate = null): int|
 
 	/**
 	 * Returns the key of last item (matching the specified predicate if given) or null if there is no such item.
-	 * The $predicate has the signature `function (mixed $value, int|string $key, array $array): bool`.
+	 * @template K of int|string
+	 * @template V
+	 * @param  array<K, V>  $array
+	 * @param  ?callable(V, K, array<K, V>): bool  $predicate
+	 * @return ?K
 	 */
 	public static function lastKey(array $array, ?callable $predicate = null): int|string|null
 	{
@@ -368,12 +378,11 @@ public static function pick(array &$array, string|int $key, mixed $default = nul
 
 
 	/**
-	 * Tests whether at least one element in the array passes the test implemented by the provided function,
-	 * which has the signature `function ($value, $key, array $array): bool`.
-	 * @template K
+	 * Tests whether at least one element in the array passes the test implemented by the provided function.
+	 * @template K of int|string
 	 * @template V
-	 * @param  iterable<K, V> $array
-	 * @param  callable(V, K, ($array is array ? array<K, V> : iterable<K, V>)): bool $predicate
+	 * @param  array<K, V>  $array
+	 * @param  callable(V, K, array<K, V>): bool  $predicate
 	 */
 	public static function some(iterable $array, callable $predicate): bool
 	{
@@ -388,12 +397,11 @@ public static function some(iterable $array, callable $predicate): bool
 
 
 	/**
-	 * Tests whether all elements in the array pass the test implemented by the provided function,
-	 * which has the signature `function ($value, $key, array $array): bool`.
-	 * @template K
+	 * Tests whether all elements in the array pass the test implemented by the provided function.
+	 * @template K of int|string
 	 * @template V
-	 * @param  iterable<K, V> $array
-	 * @param  callable(V, K, ($array is array ? array<K, V> : iterable<K, V>)): bool $predicate
+	 * @param  array<K, V>  $array
+	 * @param  callable(V, K, array<K, V>): bool  $predicate
 	 */
 	public static function every(iterable $array, callable $predicate): bool
 	{
@@ -409,11 +417,10 @@ public static function every(iterable $array, callable $predicate): bool
 
 	/**
 	 * Returns a new array containing all key-value pairs matching the given $predicate.
-	 * The callback has the signature `function (mixed $value, int|string $key, array $array): bool`.
-	 * @template K of array-key
+	 * @template K of int|string
 	 * @template V
-	 * @param  array<K, V> $array
-	 * @param  callable(V, K, array<K, V>): bool $predicate
+	 * @param  array<K, V>  $array
+	 * @param  callable(V, K, array<K, V>): bool  $predicate
 	 * @return array<K, V>
 	 */
 	public static function filter(array $array, callable $predicate): array
@@ -430,12 +437,11 @@ public static function filter(array $array, callable $predicate): array
 
 	/**
 	 * Returns an array containing the original keys and results of applying the given transform function to each element.
-	 * The function has signature `function ($value, $key, array $array): mixed`.
-	 * @template K of array-key
+	 * @template K of int|string
 	 * @template V
 	 * @template R
-	 * @param  iterable<K, V> $array
-	 * @param  callable(V, K, ($array is array ? array<K, V> : iterable<K, V>)): R $transformer
+	 * @param  array<K, V>  $array
+	 * @param  callable(V, K, array<K, V>): R  $transformer
 	 * @return array<K, R>
 	 */
 	public static function map(iterable $array, callable $transformer): array

src/Utils/Iterables.php

@@ -49,10 +49,11 @@ public static function containsKey(iterable $iterable, mixed $key): bool
 
 	/**
 	 * Returns the first item (matching the specified predicate if given). If there is no such item, it returns result of invoking $else or null.
-	 * The $predicate has the signature `function (mixed $value, mixed $key, iterable $iterable): bool`.
-	 * @template T
-	 * @param  iterable<T>  $iterable
-	 * @return ?T
+	 * @template K
+	 * @template V
+	 * @param  iterable<K, V>  $iterable
+	 * @param  ?callable(V, K, iterable<K, V>): bool  $predicate
+	 * @return ?V
 	 */
 	public static function first(iterable $iterable, ?callable $predicate = null, ?callable $else = null): mixed
 	{
@@ -67,10 +68,11 @@ public static function first(iterable $iterable, ?callable $predicate = null, ?c
 
 	/**
 	 * Returns the key of first item (matching the specified predicate if given). If there is no such item, it returns result of invoking $else or null.
-	 * The $predicate has the signature `function (mixed $value, mixed $key, iterable $iterable): bool`.
-	 * @template T
-	 * @param  iterable<T, mixed>  $iterable
-	 * @return ?T
+	 * @template K
+	 * @template V
+	 * @param  iterable<K, V>  $iterable
+	 * @param  ?callable(V, K, iterable<K, V>): bool  $predicate
+	 * @return ?K
 	 */
 	public static function firstKey(iterable $iterable, ?callable $predicate = null, ?callable $else = null): mixed
 	{
@@ -84,11 +86,10 @@ public static function firstKey(iterable $iterable, ?callable $predicate = null,
 
 
 	/**
-	 * Tests whether at least one element in the iterator passes the test implemented by the
-	 * provided callback with signature `function (mixed $value, mixed $key, iterable $iterable): bool`.
+	 * Tests whether at least one element in the iterator passes the test implemented by the provided function.
 	 * @template K
 	 * @template V
-	 * @param  iterable<K, V> $iterable
+	 * @param  iterable<K, V>  $iterable
 	 * @param  callable(V, K, iterable<K, V>): bool  $predicate
 	 */
 	public static function some(iterable $iterable, callable $predicate): bool
@@ -103,11 +104,10 @@ public static function some(iterable $iterable, callable $predicate): bool
 
 
 	/**
-	 * Tests whether all elements in the iterator pass the test implemented by the provided function,
-	 * which has the signature `function (mixed $value, mixed $key, iterable $iterable): bool`.
+	 * Tests whether all elements in the iterator pass the test implemented by the provided function.
 	 * @template K
 	 * @template V
-	 * @param  iterable<K, V> $iterable
+	 * @param  iterable<K, V>  $iterable
 	 * @param  callable(V, K, iterable<K, V>): bool  $predicate
 	 */
 	public static function every(iterable $iterable, callable $predicate): bool
@@ -123,11 +123,10 @@ public static function every(iterable $iterable, callable $predicate): bool
 
 	/**
 	 * Iterator that filters elements according to a given $predicate. Maintains original keys.
-	 * The callback has the signature `function (mixed $value, mixed $key, iterable $iterable): bool`.
 	 * @template K
 	 * @template V
-	 * @param  iterable<K, V> $iterable
-	 * @param  callable(V, K, iterable<K, V>): bool $predicate
+	 * @param  iterable<K, V>  $iterable
+	 * @param  callable(V, K, iterable<K, V>): bool  $predicate
 	 * @return \Generator<K, V>
 	 */
 	public static function filter(iterable $iterable, callable $predicate): \Generator
@@ -142,12 +141,11 @@ public static function filter(iterable $iterable, callable $predicate): \Generat
 
 	/**
 	 * Iterator that transforms values by calling $transformer. Maintains original keys.
-	 * The callback has the signature `function (mixed $value, mixed $key, iterable $iterable): bool`.
 	 * @template K
 	 * @template V
 	 * @template R
-	 * @param  iterable<K, V> $iterable
-	 * @param  callable(V, K, iterable<K, V>): R $transformer
+	 * @param  iterable<K, V>  $iterable
+	 * @param  callable(V, K, iterable<K, V>): R  $transformer
 	 * @return \Generator<K, R>
 	 */
 	public static function map(iterable $iterable, callable $transformer): \Generator