improved phpDoc

dg · dg · commit 367d3c5aa49e · 2026-02-23T04:39:23.000+01:00
diff --git a/src/Schema/Context.php b/src/Schema/Context.php
@@ -14,28 +14,30 @@ final class Context
 {
 	public bool $skipDefaults = false;
 
-	/** @var string[] */
+	/** @var list<int|string> */
 	public array $path = [];
 
 	public bool $isKey = false;
 
-	/** @var Message[] */
+	/** @var list<Message> */
 	public array $errors = [];
 
-	/** @var Message[] */
+	/** @var list<Message> */
 	public array $warnings = [];
 
-	/** @var array[] */
+	/** @var list<array{DynamicParameter, string, list<int|string>}> */
 	public array $dynamics = [];
 
 
+	/** @param  array<string, mixed>  $variables */
 	public function addError(string $message, string $code, array $variables = []): Message
 	{
 		$variables['isKey'] = $this->isKey;
 		return $this->errors[] = new Message($message, $code, $this->path, $variables);
 	}
 
 
+	/** @param  array<string, mixed>  $variables */
 	public function addWarning(string $message, string $code, array $variables = []): Message
 	{
 		return $this->warnings[] = new Message($message, $code, $this->path, $variables);
diff --git a/src/Schema/Elements/AnyOf.php b/src/Schema/Elements/AnyOf.php
@@ -18,6 +18,7 @@ final class AnyOf implements Schema
 {
 	use Base;
 
+	/** @var mixed[] */
 	private array $set;
 
 
diff --git a/src/Schema/Elements/Base.php b/src/Schema/Elements/Base.php
@@ -24,7 +24,7 @@ trait Base
 	/** @var ?\Closure(mixed): mixed */
 	private ?\Closure $before = null;
 
-	/** @var array<\Closure(mixed, Context): mixed> */
+	/** @var list<\Closure(mixed, Context): mixed> */
 	private array $transforms = [];
 	private ?string $deprecated = null;
 
@@ -43,6 +43,7 @@ public function required(bool $state = true): self
 	}
 
 
+	/** @param  callable(mixed): mixed  $handler */
 	public function before(callable $handler): self
 	{
 		$this->before = $handler(...);
@@ -56,13 +57,15 @@ public function castTo(string $type): self
 	}
 
 
+	/** @param  callable(mixed, Context): mixed  $handler */
 	public function transform(callable $handler): self
 	{
 		$this->transforms[] = $handler(...);
 		return $this;
 	}
 
 
+	/** @param  callable(mixed): bool  $handler */
 	public function assert(callable $handler, ?string $description = null): self
 	{
 		$expected = $description ?: (is_string($handler) ? "$handler()" : '#' . count($this->transforms));
@@ -144,7 +147,10 @@ private function doValidate(mixed $value, string $expected, Context $context): b
 	}
 
 
-	/** @deprecated use Nette\Schema\Validators::validateRange() */
+	/**
+	 * @deprecated use Nette\Schema\Validators::validateRange()
+	 * @param  array{?float, ?float}  $range
+	 */
 	private static function doValidateRange(mixed $value, array $range, Context $context, string $types = ''): bool
 	{
 		$isOk = $context->createChecker();
diff --git a/src/Schema/Elements/Structure.php b/src/Schema/Elements/Structure.php
@@ -29,9 +29,7 @@ final class Structure implements Schema
 	private bool $skipDefaults = false;
 
 
-	/**
-	 * @param  Schema[]  $shape
-	 */
+	/** @param Schema[]  $shape */
 	public function __construct(array $shape)
 	{
 		(function (Schema ...$items) {})(...array_values($shape));
@@ -75,13 +73,15 @@ public function skipDefaults(bool $state = true): self
 	}
 
 
+	/** @param Schema[]|self  $shape */
 	public function extend(array|self $shape): self
 	{
 		$shape = $shape instanceof self ? $shape->items : $shape;
 		return new self(array_merge($this->items, $shape));
 	}
 
 
+	/** @return Schema[] */
 	public function getShape(): array
 	{
 		return $this->items;
@@ -165,6 +165,7 @@ public function complete(mixed $value, Context $context): mixed
 	}
 
 
+	/** @param  array<mixed>  $value */
 	private function validateItems(array &$value, Context $context): void
 	{
 		$items = $this->items;
diff --git a/src/Schema/Elements/Type.php b/src/Schema/Elements/Type.php
@@ -187,6 +187,7 @@ public function complete(mixed $value, Context $context): mixed
 	}
 
 
+	/** @param  array<mixed>  $value */
 	private function validateItems(array &$value, Context $context): void
 	{
 		if (!$this->itemsValue) {
diff --git a/src/Schema/Expect.php b/src/Schema/Expect.php
@@ -30,6 +30,7 @@
  */
 final class Expect
 {
+	/** @param  list<mixed>  $args */
 	public static function __callStatic(string $name, array $args): Type
 	{
 		$type = new Type($name);
@@ -53,15 +54,14 @@ public static function anyOf(mixed ...$set): AnyOf
 	}
 
 
-	/**
-	 * @param  Schema[]  $shape
-	 */
+	/** @param Schema[]  $shape */
 	public static function structure(array $shape): Structure
 	{
 		return new Structure($shape);
 	}
 
 
+	/** @param  array<string, Schema>  $items */
 	public static function from(object $object, array $items = []): Structure
 	{
 		$ro = new \ReflectionObject($object);
diff --git a/src/Schema/Helpers.php b/src/Schema/Helpers.php
@@ -72,7 +72,7 @@ public static function getPropertyType(\ReflectionProperty|\ReflectionParameter
 
 	/**
 	 * Returns an annotation value.
-	 * @param  \ReflectionProperty  $ref
+	 * @param  \ReflectionClass<object>|\ReflectionProperty  $ref
 	 */
 	public static function parseAnnotation(\Reflector $ref, string $name): ?string
 	{
@@ -119,6 +119,7 @@ public static function validateType(mixed $value, string $expected, Context $con
 	}
 
 
+	/** @param  array{?float, ?float}  $range */
 	public static function validateRange(mixed $value, array $range, Context $context, string $types = ''): void
 	{
 		if (is_array($value) || is_string($value)) {
@@ -145,6 +146,7 @@ public static function validateRange(mixed $value, array $range, Context $contex
 	}
 
 
+	/** @param  array{?float, ?float}  $range */
 	public static function isInRange(mixed $value, array $range): bool
 	{
 		return ($range[0] === null || $value >= $range[0])
@@ -164,6 +166,7 @@ public static function validatePattern(string $value, string $pattern, Context $
 	}
 
 
+	/** @return \Closure(mixed): mixed */
 	public static function getCastStrategy(string $type): \Closure
 	{
 		if (Nette\Utils\Validators::isBuiltinType($type)) {
diff --git a/src/Schema/Processor.php b/src/Schema/Processor.php
@@ -15,6 +15,7 @@
  */
 final class Processor
 {
+	/** @var list<\Closure(Context): void> */
 	public array $onNewContext = [];
 	private Context $context;
 	private bool $skipDefaults = false;
@@ -43,6 +44,7 @@ public function process(Schema $schema, mixed $data): mixed
 
 	/**
 	 * Normalizes and validates and merges multiple data. Result is a clean completed data.
+	 * @param  list<mixed>  $dataset
 	 * @throws ValidationException
 	 */
 	public function processMultiple(Schema $schema, array $dataset): mixed
@@ -63,9 +65,7 @@ public function processMultiple(Schema $schema, array $dataset): mixed
 	}
 
 
-	/**
-	 * @return string[]
-	 */
+	/** @return list<string> */
 	public function getWarnings(): array
 	{
 		$res = [];
diff --git a/src/Schema/ValidationException.php b/src/Schema/ValidationException.php
@@ -29,9 +29,7 @@ public function __construct(?string $message, array $messages = [])
 	}
 
 
-	/**
-	 * @return string[]
-	 */
+	/** @return list<string> */
 	public function getMessages(): array
 	{
 		$res = [];
@@ -43,9 +41,7 @@ public function getMessages(): array
 	}
 
 
-	/**
-	 * @return Message[]
-	 */
+	/** @return list<Message> */
 	public function getMessageObjects(): array
 	{
 		return $this->messages;

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@ final class AnyOf implements Schema`
`18`	`18`	`{`
`19`	`19`	`use Base;`
`20`	`20`
	`21`	`+ /** @var mixed[] */`
`21`	`22`	`private array $set;`
`22`	`23`
`23`	`24`
Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ trait Base`
`24`	`24`	`/** @var ?\Closure(mixed): mixed */`
`25`	`25`	`private ?\Closure $before = null;`
`26`	`26`
`27`		`- /** @var array<\Closure(mixed, Context): mixed> */`
	`27`	`+ /** @var list<\Closure(mixed, Context): mixed> */`
`28`	`28`	`private array $transforms = [];`
`29`	`29`	`private ?string $deprecated = null;`
`30`	`30`
`@@ -43,6 +43,7 @@ public function required(bool $state = true): self`
`43`	`43`	`}`
`44`	`44`
`45`	`45`
	`46`	`+ /** @param callable(mixed): mixed $handler */`
`46`	`47`	`public function before(callable $handler): self`
`47`	`48`	`{`
`48`	`49`	`$this->before = $handler(...);`
`@@ -56,13 +57,15 @@ public function castTo(string $type): self`
`56`	`57`	`}`
`57`	`58`
`58`	`59`
	`60`	`+ /** @param callable(mixed, Context): mixed $handler */`
`59`	`61`	`public function transform(callable $handler): self`
`60`	`62`	`{`
`61`	`63`	`$this->transforms[] = $handler(...);`
`62`	`64`	`return $this;`
`63`	`65`	`}`
`64`	`66`
`65`	`67`
	`68`	`+ /** @param callable(mixed): bool $handler */`
`66`	`69`	`public function assert(callable $handler, ?string $description = null): self`
`67`	`70`	`{`
`68`	`71`	`$expected = $description ?: (is_string($handler) ? "$handler()" : '#' . count($this->transforms));`
`@@ -144,7 +147,10 @@ private function doValidate(mixed $value, string $expected, Context $context): b`
`144`	`147`	`}`
`145`	`148`
`146`	`149`
`147`		`- /** @deprecated use Nette\Schema\Validators::validateRange() */`
	`150`	`+ /**`
	`151`	`+ * @deprecated use Nette\Schema\Validators::validateRange()`
	`152`	`+ * @param array{?float, ?float} $range`
	`153`	`+ */`
`148`	`154`	`private static function doValidateRange(mixed $value, array $range, Context $context, string $types = ''): bool`
`149`	`155`	`{`
`150`	`156`	`$isOk = $context->createChecker();`
Original file line number	Diff line number	Diff line change
`@@ -29,9 +29,7 @@ final class Structure implements Schema`
`29`	`29`	`private bool $skipDefaults = false;`
`30`	`30`
`31`	`31`
`32`		`- /**`
`33`		`- * @param Schema[] $shape`
`34`		`- */`
	`32`	`+ /** @param Schema[] $shape */`
`35`	`33`	`public function __construct(array $shape)`
`36`	`34`	`{`
`37`	`35`	`(function (Schema ...$items) {})(...array_values($shape));`
`@@ -75,13 +73,15 @@ public function skipDefaults(bool $state = true): self`
`75`	`73`	`}`
`76`	`74`
`77`	`75`
	`76`	`+ /** @param Schema[]\|self $shape */`
`78`	`77`	`public function extend(array\|self $shape): self`
`79`	`78`	`{`
`80`	`79`	`$shape = $shape instanceof self ? $shape->items : $shape;`
`81`	`80`	`return new self(array_merge($this->items, $shape));`
`82`	`81`	`}`
`83`	`82`
`84`	`83`
	`84`	`+ /** @return Schema[] */`
`85`	`85`	`public function getShape(): array`
`86`	`86`	`{`
`87`	`87`	`return $this->items;`
`@@ -165,6 +165,7 @@ public function complete(mixed $value, Context $context): mixed`
`165`	`165`	`}`
`166`	`166`
`167`	`167`
	`168`	`+ /** @param array<mixed> $value */`
`168`	`169`	`private function validateItems(array &$value, Context $context): void`
`169`	`170`	`{`
`170`	`171`	`$items = $this->items;`
Original file line number	Diff line number	Diff line change
`@@ -187,6 +187,7 @@ public function complete(mixed $value, Context $context): mixed`
`187`	`187`	`}`
`188`	`188`
`189`	`189`
	`190`	`+ /** @param array<mixed> $value */`
`190`	`191`	`private function validateItems(array &$value, Context $context): void`
`191`	`192`	`{`
`192`	`193`	`if (!$this->itemsValue) {`
Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,7 @@`
`30`	`30`	`*/`
`31`	`31`	`final class Expect`
`32`	`32`	`{`
	`33`	`+ /** @param list<mixed> $args */`
`33`	`34`	`public static function __callStatic(string $name, array $args): Type`
`34`	`35`	`{`
`35`	`36`	`$type = new Type($name);`
`@@ -53,15 +54,14 @@ public static function anyOf(mixed ...$set): AnyOf`
`53`	`54`	`}`
`54`	`55`
`55`	`56`
`56`		`- /**`
`57`		`- * @param Schema[] $shape`
`58`		`- */`
	`57`	`+ /** @param Schema[] $shape */`
`59`	`58`	`public static function structure(array $shape): Structure`
`60`	`59`	`{`
`61`	`60`	`return new Structure($shape);`
`62`	`61`	`}`
`63`	`62`
`64`	`63`
	`64`	`+ /** @param array<string, Schema> $items */`
`65`	`65`	`public static function from(object $object, array $items = []): Structure`
`66`	`66`	`{`
`67`	`67`	`$ro = new \ReflectionObject($object);`
Original file line number	Diff line number	Diff line change
`@@ -72,7 +72,7 @@ public static function getPropertyType(\ReflectionProperty\|\ReflectionParameter`
`72`	`72`
`73`	`73`	`/**`
`74`	`74`	`* Returns an annotation value.`
`75`		`- * @param \ReflectionProperty $ref`
	`75`	`+ * @param \ReflectionClass<object>\|\ReflectionProperty $ref`
`76`	`76`	`*/`
`77`	`77`	`public static function parseAnnotation(\Reflector $ref, string $name): ?string`
`78`	`78`	`{`
`@@ -119,6 +119,7 @@ public static function validateType(mixed $value, string $expected, Context $con`
`119`	`119`	`}`
`120`	`120`
`121`	`121`
	`122`	`+ /** @param array{?float, ?float} $range */`
`122`	`123`	`public static function validateRange(mixed $value, array $range, Context $context, string $types = ''): void`
`123`	`124`	`{`
`124`	`125`	`if (is_array($value) \|\| is_string($value)) {`
`@@ -145,6 +146,7 @@ public static function validateRange(mixed $value, array $range, Context $contex`
`145`	`146`	`}`
`146`	`147`
`147`	`148`
	`149`	`+ /** @param array{?float, ?float} $range */`
`148`	`150`	`public static function isInRange(mixed $value, array $range): bool`
`149`	`151`	`{`
`150`	`152`	`return ($range[0] === null \|\| $value >= $range[0])`
`@@ -164,6 +166,7 @@ public static function validatePattern(string $value, string $pattern, Context $`
`164`	`166`	`}`
`165`	`167`
`166`	`168`
	`169`	`+ /** @return \Closure(mixed): mixed */`
`167`	`170`	`public static function getCastStrategy(string $type): \Closure`
`168`	`171`	`{`
`169`	`172`	`if (Nette\Utils\Validators::isBuiltinType($type)) {`
Original file line number	Diff line number	Diff line change
`@@ -29,9 +29,7 @@ public function __construct(?string $message, array $messages = [])`
`29`	`29`	`}`
`30`	`30`
`31`	`31`
`32`		`- /**`
`33`		`- * @return string[]`
`34`		`- */`
	`32`	`+ /** @return list<string> */`
`35`	`33`	`public function getMessages(): array`
`36`	`34`	`{`
`37`	`35`	`$res = [];`
`@@ -43,9 +41,7 @@ public function getMessages(): array`
`43`	`41`	`}`
`44`	`42`
`45`	`43`
`46`		`- /**`
`47`		`- * @return Message[]`
`48`		`- */`
	`44`	`+ /** @return list<Message> */`
`49`	`45`	`public function getMessageObjects(): array`
`50`	`46`	`{`
`51`	`47`	`return $this->messages;`