improved PHPDoc descriptions

Author: dg

src/Schema/Context.php

@@ -10,6 +10,9 @@
 use function count;
 
 
+/**
+ * Accumulates errors and warnings during schema validation and tracks the current path.
+ */
 final class Context
 {
 	public bool $skipDefaults = false;
@@ -44,7 +47,10 @@ public function addWarning(string $message, string $code, array $variables = [])
 	}
 
 
-	/** @return \Closure(): bool */
+	/**
+	 * Returns a closure that returns true as long as no new errors have been added since the call.
+	 * @return \Closure(): bool
+	 */
 	public function createChecker(): \Closure
 	{
 		$count = count($this->errors);

src/Schema/Elements/AnyOf.php

@@ -14,6 +14,9 @@
 use function array_merge, array_unique, implode, is_array;
 
 
+/**
+ * Schema that accepts any of a fixed set of values or sub-schemas (union type / enumeration).
+ */
 final class AnyOf implements Schema
 {
 	use Base;
@@ -32,20 +35,29 @@ public function __construct(mixed ...$set)
 	}
 
 
+	/**
+	 * Sets the first variant as the default value (instead of null).
+	 */
 	public function firstIsDefault(): self
 	{
 		$this->default = $this->set[0];
 		return $this;
 	}
 
 
+	/**
+	 * Allows null as an accepted value in addition to the defined variants.
+	 */
 	public function nullable(): self
 	{
 		$this->set[] = null;
 		return $this;
 	}
 
 
+	/**
+	 * Allows the value to be a DynamicParameter as an accepted variant.
+	 */
 	public function dynamic(): self
 	{
 		$this->set[] = new Type(Nette\Schema\DynamicParameter::class);

src/Schema/Elements/Base.php

@@ -43,29 +43,41 @@ public function required(bool $state = true): self
 	}
 
 
-	/** @param  callable(mixed): mixed  $handler */
+	/**
+	 * Sets a pre-normalization callback applied to the raw input value before any validation.
+	 * @param  callable(mixed): mixed  $handler
+	 */
 	public function before(callable $handler): self
 	{
 		$this->before = $handler(...);
 		return $this;
 	}
 
 
+	/**
+	 * Casts the validated value to a built-in type or instantiates the given class.
+	 */
 	public function castTo(string $type): self
 	{
 		return $this->transform(Helpers::getCastStrategy($type));
 	}
 
 
-	/** @param  callable(mixed, Context): mixed  $handler */
+	/**
+	 * Adds a post-validation transformation callback. The handler may also report errors via Context.
+	 * @param  callable(mixed, Context): mixed  $handler
+	 */
 	public function transform(callable $handler): self
 	{
 		$this->transforms[] = $handler(...);
 		return $this;
 	}
 
 
-	/** @param  callable(mixed): bool  $handler */
+	/**
+	 * Adds a custom validation assertion; optionally describe it for error messages.
+	 * @param  callable(mixed): bool  $handler
+	 */
 	public function assert(callable $handler, ?string $description = null): self
 	{
 		$expected = $description ?? (is_string($handler) ? "$handler()" : '#' . count($this->transforms));
@@ -82,7 +94,9 @@ public function assert(callable $handler, ?string $description = null): self
 	}
 
 
-	/** Marks as deprecated */
+	/**
+	 * Marks the item as deprecated; emits a warning with the given message when the item is used.
+	 */
 	public function deprecated(string $message = 'The item %path% is deprecated.'): self
 	{
 		$this->deprecated = $message;

src/Schema/Elements/Structure.php

@@ -39,6 +39,9 @@ public function __construct(array $shape)
 	}
 
 
+	/**
+	 * Not supported for structures; always throws.
+	 */
 	public function default(mixed $value): self
 	{
 		throw new Nette\InvalidStateException('Structure cannot have default value.');
@@ -59,21 +62,30 @@ public function max(?int $max): self
 	}
 
 
+	/**
+	 * Allows extra keys not defined in the shape, validating their values against the given type.
+	 */
 	public function otherItems(string|Schema $type = 'mixed'): self
 	{
 		$this->otherItems = $type instanceof Schema ? $type : new Type($type);
 		return $this;
 	}
 
 
+	/**
+	 * When enabled, properties whose value equals the default are omitted from the output.
+	 */
 	public function skipDefaults(bool $state = true): self
 	{
 		$this->skipDefaults = $state;
 		return $this;
 	}
 
 
-	/** @param Schema[]|self  $shape */
+	/**
+	 * Creates a new structure by merging this shape with additional properties.
+	 * @param  Schema[]|self  $shape
+	 */
 	public function extend(array|self $shape): self
 	{
 		$shape = $shape instanceof self ? $shape->items : $shape;

src/Schema/Elements/Type.php

@@ -36,20 +36,29 @@ public function __construct(string $type)
 	}
 
 
+	/**
+	 * Allows the value to be null in addition to the declared type.
+	 */
 	public function nullable(): self
 	{
 		$this->type = 'null|' . $this->type;
 		return $this;
 	}
 
 
+	/**
+	 * Controls whether the default value is merged with the input array (enabled by default).
+	 */
 	public function mergeDefaults(bool $state = true): self
 	{
 		$this->merge = $state;
 		return $this;
 	}
 
 
+	/**
+	 * Allows the value to be a DynamicParameter, which is recorded for deferred validation.
+	 */
 	public function dynamic(): self
 	{
 		$this->type = DynamicParameter::class . '|' . $this->type;
@@ -86,6 +95,9 @@ public function items(string|Schema $valueType = 'mixed', string|Schema|null $ke
 	}
 
 
+	/**
+	 * Sets a regex pattern the string value must match entirely (anchored to start and end).
+	 */
 	public function pattern(?string $pattern): self
 	{
 		$this->pattern = $pattern;

src/Schema/Expect.php

@@ -42,26 +42,38 @@ public static function __callStatic(string $name, array $args): Type
 	}
 
 
+	/**
+	 * Creates a schema for a custom type expression (e.g., 'int|string', 'null|float').
+	 */
 	public static function type(string $type): Type
 	{
 		return new Type($type);
 	}
 
 
+	/**
+	 * Creates a union schema that accepts any of the given values or sub-schemas.
+	 */
 	public static function anyOf(mixed ...$set): AnyOf
 	{
 		return new AnyOf(...$set);
 	}
 
 
-	/** @param Schema[]  $shape */
+	/**
+	 * Creates a structure schema with defined properties; output is stdClass.
+	 * @param  Schema[]  $shape
+	 */
 	public static function structure(array $shape): Structure
 	{
 		return new Structure($shape);
 	}
 
 
-	/** @param  array<string, Schema>  $items */
+	/**
+	 * Generates a structure schema from a class instance by reflecting its properties or constructor parameters.
+	 * @param  array<string, Schema>  $items  Optional overrides for specific properties.
+	 */
 	public static function from(object $object, array $items = []): Structure
 	{
 		$ro = new \ReflectionObject($object);
@@ -95,6 +107,8 @@ public static function from(object $object, array $items = []): Structure
 
 
 	/**
+	 * Creates an array schema. When passed Schema elements, behaves like structure() but outputs an array.
+	 * Without Schema elements, creates a plain array type with the given default value.
 	 * @param  mixed[]  $shape
 	 */
 	public static function array(?array $shape = []): Structure|Type
@@ -106,12 +120,18 @@ public static function array(?array $shape = []): Structure|Type
 	}
 
 
+	/**
+	 * Creates an associative or indexed array schema where every value matches the given type.
+	 */
 	public static function arrayOf(string|Schema $valueType, string|Schema|null $keyType = null): Type
 	{
 		return (new Type('array'))->items($valueType, $keyType);
 	}
 
 
+	/**
+	 * Creates a list schema (sequentially indexed from 0) where every element matches the given type.
+	 */
 	public static function listOf(string|Schema $type): Type
 	{
 		return (new Type('list'))->items($type);

src/Schema/Helpers.php

@@ -54,6 +54,9 @@ public static function merge(mixed $value, mixed $base): mixed
 	}
 
 
+	/**
+	 * Returns the type of a property or parameter as a string, or null if not determinable.
+	 */
 	public static function getPropertyType(\ReflectionProperty|\ReflectionParameter $prop): ?string
 	{
 		if ($type = Nette\Utils\Type::fromReflection($prop)) {
@@ -89,6 +92,9 @@ public static function parseAnnotation(\ReflectionClass|\ReflectionProperty $ref
 	}
 
 
+	/**
+	 * Formats a value for use in error messages (e.g., 'hello', true, object stdClass).
+	 */
 	public static function formatValue(mixed $value): string
 	{
 		if ($value instanceof DynamicParameter) {
@@ -105,6 +111,9 @@ public static function formatValue(mixed $value): string
 	}
 
 
+	/**
+	 * Adds a TypeMismatch error to the context if the value does not match the expected type.
+	 */
 	public static function validateType(mixed $value, string $expected, Context $context): void
 	{
 		if (!Nette\Utils\Validators::is($value, $expected)) {
@@ -119,7 +128,10 @@ public static function validateType(mixed $value, string $expected, Context $con
 	}
 
 
-	/** @param  array{?float, ?float}  $range */
+	/**
+	 * Adds a range error to the context if the value (or its length for strings/arrays) is outside the given range.
+	 * @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)) {
@@ -146,14 +158,20 @@ public static function validateRange(mixed $value, array $range, Context $contex
 	}
 
 
-	/** @param  array{?float, ?float}  $range */
+	/**
+	 * Checks whether a value falls within the given [min, max] range (null means no bound).
+	 * @param  array{?float, ?float}  $range
+	 */
 	public static function isInRange(mixed $value, array $range): bool
 	{
 		return ($range[0] === null || $value >= $range[0])
 			&& ($range[1] === null || $value <= $range[1]);
 	}
 
 
+	/**
+	 * Adds a PatternMismatch error to the context if the value does not match the pattern.
+	 */
 	public static function validatePattern(string $value, string $pattern, Context $context): void
 	{
 		if (!preg_match("\x01^(?:$pattern)$\x01Du", $value)) {
@@ -166,7 +184,10 @@ public static function validatePattern(string $value, string $pattern, Context $
 	}
 
 
-	/** @return \Closure(mixed): mixed */
+	/**
+	 * Returns a closure that casts a value to the given type (built-in, class with constructor, or plain class).
+	 * @return \Closure(mixed): mixed
+	 */
 	public static function getCastStrategy(string $type): \Closure
 	{
 		if (Nette\Utils\Validators::isBuiltinType($type)) {

src/Schema/Message.php

@@ -10,6 +10,9 @@
 use function implode, preg_replace_callback;
 
 
+/**
+ * Represents a single validation error or warning with a message template, error code, path, and variables.
+ */
 final class Message
 {
 	/** variables: {value: mixed, expected: string} */
@@ -72,6 +75,9 @@ public function __construct(
 	}
 
 
+	/**
+	 * Formats the message template by substituting %variable% placeholders with their values.
+	 */
 	public function toString(): string
 	{
 		$vars = $this->variables;

src/Schema/Processor.php

@@ -21,6 +21,9 @@ final class Processor
 	private bool $skipDefaults = false;
 
 
+	/**
+	 * When enabled, properties with default values are omitted from the output.
+	 */
 	public function skipDefaults(bool $value = true): void
 	{
 		$this->skipDefaults = $value;
@@ -65,7 +68,10 @@ public function processMultiple(Schema $schema, array $dataset): mixed
 	}
 
 
-	/** @return list<string> */
+	/**
+	 * Returns all deprecation warnings collected during the last processing run.
+	 * @return list<string>
+	 */
 	public function getWarnings(): array
 	{
 		$res = [];