improved phpDoc

Author: dg

src/HtmlStringable.php

@@ -10,10 +10,13 @@
 namespace Nette;
 
 
+/**
+ * Represents object convertible to HTML string.
+ */
 interface HtmlStringable
 {
 	/**
-	 * Returns string in HTML format
+	 * Returns string in HTML format.
 	 */
 	function __toString(): string;
 }

src/Iterators/CachingIterator.php

@@ -13,16 +13,19 @@
 
 
 /**
- * Smarter caching iterator.
+ * Enhanced caching iterator with first/last/counter tracking.
  *
+ * @template TKey
+ * @template TValue
+ * @extends \CachingIterator<TKey, TValue, \Iterator<TKey, TValue>>
  * @property-read bool $first
  * @property-read bool $last
  * @property-read bool $empty
  * @property-read bool $odd
  * @property-read bool $even
  * @property-read int $counter
- * @property-read mixed $nextKey
- * @property-read mixed $nextValue
+ * @property-read TKey $nextKey
+ * @property-read TValue $nextValue
  */
 class CachingIterator extends \CachingIterator implements \Countable
 {
@@ -31,6 +34,7 @@ class CachingIterator extends \CachingIterator implements \Countable
 	private int $counter = 0;
 
 
+	/** @param  iterable<TKey, TValue>|\stdClass  $iterable */
 	public function __construct(iterable|\stdClass $iterable)
 	{
 		$iterable = $iterable instanceof \stdClass
@@ -58,45 +62,30 @@ public function isLast(?int $gridWidth = null): bool
 	}
 
 
-	/**
-	 * Is the iterator empty?
-	 */
 	public function isEmpty(): bool
 	{
 		return $this->counter === 0;
 	}
 
 
-	/**
-	 * Is the counter odd?
-	 */
 	public function isOdd(): bool
 	{
 		return $this->counter % 2 === 1;
 	}
 
 
-	/**
-	 * Is the counter even?
-	 */
 	public function isEven(): bool
 	{
 		return $this->counter % 2 === 0;
 	}
 
 
-	/**
-	 * Returns the counter.
-	 */
 	public function getCounter(): int
 	{
 		return $this->counter;
 	}
 
 
-	/**
-	 * Returns the count of elements.
-	 */
 	public function count(): int
 	{
 		$inner = $this->getInnerIterator();
@@ -131,18 +120,14 @@ public function rewind(): void
 	}
 
 
-	/**
-	 * Returns the next key.
-	 */
+	/** @return TKey */
 	public function getNextKey(): mixed
 	{
 		return $this->getInnerIterator()->key();
 	}
 
 
-	/**
-	 * Returns the next element.
-	 */
+	/** @return TValue */
 	public function getNextValue(): mixed
 	{
 		return $this->getInnerIterator()->current();

src/SmartObject.php

@@ -22,6 +22,7 @@
 trait SmartObject
 {
 	/**
+	 * @param  mixed[]  $args
 	 * @return mixed
 	 * @throws MemberAccessException
 	 */
@@ -47,6 +48,8 @@ public function __call(string $name, array $args)
 
 
 	/**
+	 * @param  mixed[]  $args
+	 * @return never
 	 * @throws MemberAccessException
 	 */
 	public static function __callStatic(string $name, array $args)

src/StaticClass.php

@@ -11,7 +11,7 @@
 
 
 /**
- * Static class.
+ * Prevents instantiation.
  */
 trait StaticClass
 {

src/Translator.php

@@ -11,7 +11,7 @@
 
 
 /**
- * Translator adapter.
+ * Translation provider.
  */
 interface Translator
 {

src/Utils/ArrayHash.php

@@ -14,7 +14,7 @@
 
 
 /**
- * Provides objects to work as array.
+ * Array-like object with property access.
  * @template T
  * @implements \IteratorAggregate<array-key, T>
  * @implements \ArrayAccess<array-key, T>
@@ -39,7 +39,6 @@ public static function from(array $array, bool $recursive = true): static
 
 
 	/**
-	 * Returns an iterator over all items.
 	 * @return \Iterator<array-key, T>
 	 */
 	public function &getIterator(): \Iterator
@@ -50,9 +49,6 @@ public function &getIterator(): \Iterator
 	}
 
 
-	/**
-	 * Returns items count.
-	 */
 	public function count(): int
 	{
 		return count((array) $this);

src/Utils/ArrayList.php

@@ -14,13 +14,14 @@
 
 
 /**
- * Provides the base class for a generic list (items can be accessed by index).
+ * Generic list with integer indices.
  * @template T
  * @implements \IteratorAggregate<int, T>
  * @implements \ArrayAccess<int, T>
  */
 class ArrayList implements \ArrayAccess, \Countable, \IteratorAggregate
 {
+	/** @var list<T> */
 	private array $list = [];
 
 
@@ -41,7 +42,6 @@ public static function from(array $array): static
 
 
 	/**
-	 * Returns an iterator over all items.
 	 * @return \Iterator<int, T>
 	 */
 	public function &getIterator(): \Iterator
@@ -52,9 +52,6 @@ public function &getIterator(): \Iterator
 	}
 
 
-	/**
-	 * Returns items count.
-	 */
 	public function count(): int
 	{
 		return count($this->list);
@@ -63,7 +60,7 @@ public function count(): int
 
 	/**
 	 * Replaces or appends an item.
-	 * @param  int|null  $index
+	 * @param  ?int  $index
 	 * @param  T  $value
 	 * @throws Nette\OutOfRangeException
 	 */

src/Utils/Arrays.php

@@ -79,7 +79,7 @@ public static function &getRef(array &$array, string|int|array $key): mixed
 	 * @template T2
 	 * @param  array<T1>  $array1
 	 * @param  array<T2>  $array2
-	 * @return array<T1|T2>
+	 * @return array<T1|T2|array<mixed>>
 	 */
 	public static function mergeTree(array $array1, array $array2): array
 	{
@@ -96,6 +96,7 @@ public static function mergeTree(array $array1, array $array2): array
 
 	/**
 	 * Returns zero-indexed position of given array key. Returns null if key is not found.
+	 * @param  array<mixed>  $array
 	 */
 	public static function getKeyOffset(array $array, string|int $key): ?int
 	{
@@ -104,6 +105,7 @@ public static function getKeyOffset(array $array, string|int $key): ?int
 
 
 	/**
+	 * @param  array<mixed>  $array
 	 * @deprecated  use  getKeyOffset()
 	 */
 	public static function searchKey(array $array, string|int $key): ?int
@@ -114,6 +116,7 @@ public static function searchKey(array $array, string|int $key): ?int
 
 	/**
 	 * Tests an array for the presence of value.
+	 * @param  array<mixed>  $array
 	 */
 	public static function contains(array $array, mixed $value): bool
 	{
@@ -125,9 +128,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.
 	 * @template K of int|string
 	 * @template V
+	 * @template E
 	 * @param  array<K, V>  $array
 	 * @param  ?callable(V, K, array<K, V>): bool  $predicate
-	 * @return ?V
+	 * @param  ?callable(): E  $else
+	 * @return ($else is null ? ?V : V|E)
 	 */
 	public static function first(array $array, ?callable $predicate = null, ?callable $else = null): mixed
 	{
@@ -142,9 +147,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.
 	 * @template K of int|string
 	 * @template V
+	 * @template E
 	 * @param  array<K, V>  $array
 	 * @param  ?callable(V, K, array<K, V>): bool  $predicate
-	 * @return ?V
+	 * @param  ?callable(): E  $else
+	 * @return ($else is null ? ?V : V|E)
 	 */
 	public static function last(array $array, ?callable $predicate = null, ?callable $else = null): mixed
 	{
@@ -196,6 +203,8 @@ public static function lastKey(array $array, ?callable $predicate = null): int|s
 	/**
 	 * Inserts the contents of the $inserted array into the $array immediately after the $key.
 	 * If $key is null (or does not exist), it is inserted at the beginning.
+	 * @param  array<mixed>  $array
+	 * @param  array<mixed>  $inserted
 	 */
 	public static function insertBefore(array &$array, string|int|null $key, array $inserted): void
 	{
@@ -209,6 +218,8 @@ public static function insertBefore(array &$array, string|int|null $key, array $
 	/**
 	 * Inserts the contents of the $inserted array into the $array before the $key.
 	 * If $key is null (or does not exist), it is inserted at the end.
+	 * @param  array<mixed>  $array
+	 * @param  array<mixed>  $inserted
 	 */
 	public static function insertAfter(array &$array, string|int|null $key, array $inserted): void
 	{
@@ -224,6 +235,7 @@ public static function insertAfter(array &$array, string|int|null $key, array $i
 
 	/**
 	 * Renames key in array.
+	 * @param  array<mixed>  $array
 	 */
 	public static function renameKey(array &$array, string|int $oldKey, string|int $newKey): bool
 	{
@@ -260,6 +272,8 @@ public static function grep(
 
 	/**
 	 * Transforms multidimensional array to flat array.
+	 * @param  array<mixed>  $array
+	 * @return array<mixed>
 	 */
 	public static function flatten(array $array, bool $preserveKeys = false): array
 	{
@@ -284,7 +298,9 @@ public static function isList(mixed $value): bool
 
 	/**
 	 * Reformats table to associative tree. Path looks like 'field|field[]field->field=field'.
-	 * @param  string|string[]  $path
+	 * @param  array<mixed>  $array
+	 * @param  string|list<string>  $path
+	 * @return array<mixed>|\stdClass
 	 */
 	public static function associate(array $array, string|array $path): array|\stdClass
 	{
@@ -338,6 +354,8 @@ public static function associate(array $array, string|array $path): array|\stdCl
 
 	/**
 	 * Normalizes array to associative array. Replace numeric keys with their values, the new value will be $filling.
+	 * @param  array<mixed>  $array
+	 * @return array<string, mixed>
 	 */
 	public static function normalize(array $array, mixed $filling = null): array
 	{
@@ -481,6 +499,7 @@ public static function mapWithKeys(array $array, callable $transformer): array
 	/**
 	 * Invokes all callbacks and returns array of results.
 	 * @param  callable[]  $callbacks
+	 * @return array<mixed>
 	 */
 	public static function invoke(iterable $callbacks, mixed ...$args): array
 	{
@@ -496,6 +515,7 @@ public static function invoke(iterable $callbacks, mixed ...$args): array
 	/**
 	 * Invokes method on every object in an array and returns array of results.
 	 * @param  object[]  $objects
+	 * @return array<mixed>
 	 */
 	public static function invokeMethod(iterable $objects, string $method, mixed ...$args): array
 	{
@@ -511,6 +531,7 @@ public static function invokeMethod(iterable $objects, string $method, mixed ...
 	/**
 	 * Copies the elements of the $array array to the $object object and then returns it.
 	 * @template T of object
+	 * @param  iterable<mixed>  $array
 	 * @param  T  $object
 	 * @return T
 	 */

src/Utils/Callback.php

@@ -22,6 +22,9 @@ final class Callback
 
 	/**
 	 * Invokes internal PHP function with own error handler.
+	 * @param  callable-string  $function
+	 * @param  list<mixed>  $args
+	 * @param  callable(string, int): (bool|void|null)  $onError
 	 */
 	public static function invokeSafe(string $function, array $args, callable $onError): mixed
 	{
@@ -116,6 +119,7 @@ public static function isStatic(callable $callable): bool
 
 	/**
 	 * Unwraps closure created by Closure::fromCallable().
+	 * @return callable|array{object|class-string, string}|string
 	 */
 	public static function unwrap(\Closure $closure): callable|array
 	{