improved phpDoc

Author: dg

src/Bridges/FormsLatte/Nodes/FieldNNameNode.php

@@ -98,7 +98,10 @@ private function init(Tag $tag): void
 	}
 
 
-	/** @internal */
+	/**
+	 * @internal
+	 * @return string[]
+	 */
 	public static function findUsedAttributes(ElementNode $el): array
 	{
 		$res = [];

src/Bridges/FormsLatte/Nodes/FormContainerNode.php

@@ -26,7 +26,7 @@ class FormContainerNode extends StatementNode
 	public AreaNode $content;
 
 
-	/** @return \Generator<int, ?array, array{AreaNode, ?Tag}, static|AreaNode> */
+	/** @return \Generator<int, ?array<mixed>, array{AreaNode, ?Tag}, static|AreaNode> */
 	public static function create(Tag $tag): \Generator
 	{
 		$tag->outputMode = $tag::OutputRemoveIndentation;

src/Bridges/FormsLatte/Nodes/FormNode.php

@@ -34,7 +34,7 @@ class FormNode extends StatementNode
 	public ?Position $endLine;
 
 
-	/** @return \Generator<int, ?array, array{AreaNode, ?Tag}, static|AreaNode> */
+	/** @return \Generator<int, ?array<mixed>, array{AreaNode, ?Tag}, static|AreaNode> */
 	public static function create(Tag $tag): \Generator
 	{
 		if ($tag->isNAttribute()) {

src/Bridges/FormsLatte/Nodes/LabelNode.php

@@ -35,7 +35,7 @@ class LabelNode extends StatementNode
 	public ?Position $endLine;
 
 
-	/** @return \Generator<int, ?array, array{AreaNode, ?Tag}, static|AreaNode> */
+	/** @return \Generator<int, ?array<mixed>, array{AreaNode, ?Tag}, static|AreaNode> */
 	public static function create(Tag $tag): \Generator
 	{
 		if ($tag->isNAttribute()) {

src/Bridges/FormsLatte/Runtime.php

@@ -35,6 +35,7 @@ public static function initializeForm(Form $form): void
 
 	/**
 	 * Renders form begin.
+	 * @param array<string, mixed>  $attrs
 	 */
 	public static function renderFormBegin(Form $form, array $attrs, bool $withTags = true): string
 	{
@@ -77,6 +78,7 @@ public static function renderFormEnd(Form $form, bool $withTags = true): string
 	}
 
 
+	/** @param object{formsStack: Form[]}  $global */
 	public static function item($item, $global): object
 	{
 		if (is_object($item)) {

src/Forms/Container.php

@@ -18,9 +18,10 @@
 /**
  * Container for form controls.
  *
- * @property   ArrayHash $values
+ * @property   ArrayHash<mixed> $values
  * @property-read \Iterator $controls
- * @property-read Form|null $form
+ * @property-read ?Form $form
+ * @implements \ArrayAccess<string|int, Nette\ComponentModel\IComponent>
  */
 class Container extends Nette\ComponentModel\Container implements \ArrayAccess
 {
@@ -30,12 +31,12 @@ class Container extends Nette\ComponentModel\Container implements \ArrayAccess
 
 	/**
 	 * Occurs when the form was validated
-	 * @var array<callable(self, array|object): void|callable(array|object): void>
+	 * @var array<callable(self, mixed[]|object): void | callable(mixed[]|object): void>
 	 */
 	public array $onValidate = [];
 	protected ?ControlGroup $currentGroup = null;
 
-	/** @var callable[]  extension methods */
+	/** @var array<string, callable(self): mixed> */
 	private static array $extMethods = [];
 	private ?bool $validated = false;
 	private ?string $mappedType = null;
@@ -46,6 +47,7 @@ class Container extends Nette\ComponentModel\Container implements \ArrayAccess
 
 	/**
 	 * Fill-in with default values.
+	 * @param mixed[]|object $data
 	 */
 	public function setDefaults(array|object $data, bool $erase = false): static
 	{
@@ -57,6 +59,7 @@ public function setDefaults(array|object $data, bool $erase = false): static
 
 	/**
 	 * Fill-in with values.
+	 * @param mixed[]|object $values
 	 * @internal
 	 */
 	public function setValues(array|object $values, bool $erase = false, bool $onlyDisabled = false): static
@@ -83,7 +86,10 @@ public function setValues(array|object $values, bool $erase = false, bool $onlyD
 
 	/**
 	 * Returns the values submitted by the form.
-	 * @param  Control[]|null  $controls
+	 * @template T of object
+	 * @param  class-string<T>|T|'array'|true|null  $returnType
+	 * @param  ?list<Control>  $controls
+	 * @return ($returnType is class-string<T>|T ? T : ($returnType is 'array'|true ? mixed[] : ArrayHash<mixed>))
 	 */
 	public function getValues(string|object|bool|null $returnType = null, ?array $controls = null): object|array
 	{
@@ -121,7 +127,10 @@ public function getValues(string|object|bool|null $returnType = null, ?array $co
 
 	/**
 	 * Returns the potentially unvalidated values submitted by the form.
-	 * @param  Control[]|null  $controls
+	 * @template T of object
+	 * @param  class-string<T>|T|'array'|null  $returnType
+	 * @param  ?list<Control>  $controls
+	 * @return ($returnType is class-string<T>|T ? T : ($returnType is 'array' ? mixed[] : ArrayHash<mixed>))
 	 */
 	public function getUntrustedValues(string|object|null $returnType = null, ?array $controls = null): object|array
 	{
@@ -179,6 +188,7 @@ public function getUnsafeValues($returnType, ?array $controls = null)
 	}
 
 
+	/** @param class-string  $type */
 	public function setMappedType(string $type): static
 	{
 		$this->mappedType = $type;
@@ -237,6 +247,7 @@ public function validate(?array $controls = null): void
 
 	/**
 	 * Returns all validation errors.
+	 * @return string[]
 	 */
 	public function getErrors(): array
 	{
@@ -286,6 +297,7 @@ public function addComponent(
 
 	/**
 	 * Iterates over all form controls.
+	 * @return iterable<Control>
 	 */
 	public function getControls(): \Iterator
 	{
@@ -464,6 +476,7 @@ public function addCheckbox(string $name, string|Stringable|null $caption = null
 
 	/**
 	 * Adds set of radio button controls to the form.
+	 * @param ?mixed[]  $items
 	 */
 	public function addRadioList(
 		string $name,
@@ -477,6 +490,7 @@ public function addRadioList(
 
 	/**
 	 * Adds set of checkbox controls to the form.
+	 * @param ?mixed[]  $items
 	 */
 	public function addCheckboxList(
 		string $name,
@@ -490,6 +504,7 @@ public function addCheckboxList(
 
 	/**
 	 * Adds select box control that allows single item selection.
+	 * @param ?mixed[]  $items
 	 */
 	public function addSelect(
 		string $name,
@@ -505,6 +520,7 @@ public function addSelect(
 
 	/**
 	 * Adds select box control that allows multiple item selection.
+	 * @param ?mixed[]  $items
 	 */
 	public function addMultiSelect(
 		string $name,
@@ -578,6 +594,7 @@ public function addContainer(string|int $name): self
 	/********************* extension methods ****************d*g**/
 
 
+	/** @param mixed[] $args */
 	public function __call(string $name, array $args)
 	{
 		if (isset(self::$extMethods[$name])) {

src/Forms/Control.php

@@ -32,6 +32,7 @@ function validate(): void;
 
 	/**
 	 * Returns errors corresponding to control.
+	 * @return string[]
 	 */
 	function getErrors(): array;
 

src/Forms/ControlGroup.php

@@ -18,7 +18,10 @@
  */
 class ControlGroup
 {
+	/** @var \WeakMap<Control, null> */
 	protected \WeakMap $controls;
+
+	/** @var array<string, mixed> */
 	private array $options = [];
 
 
@@ -28,6 +31,7 @@ public function __construct()
 	}
 
 
+	/** @param Control|Container|iterable<Control|Container> ...$items */
 	public function add(...$items): static
 	{
 		foreach ($items as $item) {
@@ -115,6 +119,7 @@ public function getOption(string $key): mixed
 
 	/**
 	 * Returns user-specific options.
+	 * @return array<string, mixed>
 	 */
 	public function getOptions(): array
 	{

src/Forms/Controls/BaseControl.php

@@ -34,8 +34,8 @@
  * @property-read Html $labelPrototype
  * @property   bool $required
  * @property-read bool $filled
- * @property-read array $errors
- * @property-read array $options
+ * @property-read string[] $errors
+ * @property-read array<string,mixed> $options
  * @property-read string $error
  */
 abstract class BaseControl extends Nette\ComponentModel\Component implements Control
@@ -49,15 +49,19 @@ abstract class BaseControl extends Nette\ComponentModel\Component implements Con
 	/** @var bool|bool[] */
 	protected bool|array $disabled = false;
 
-	/** @var callable[][]  extension methods */
+	/** @var array<string, array<class-string, callable(self): mixed>> */
 	private static array $extMethods = [];
 	private string|Stringable|null $caption;
+
+	/** @var string[] */
 	private array $errors = [];
 	private ?bool $omitted = null;
 	private Rules $rules;
 
 	/** true means autodetect */
 	private Nette\Localization\Translator|bool|null $translator = true;
+
+	/** @var array<string, mixed> */
 	private array $options = [];
 
 
@@ -397,6 +401,7 @@ public function translate($value, ...$parameters): mixed
 
 	/**
 	 * Adds a validation rule.
+	 * @param  (callable(self): bool)|string  $validator
 	 * @return static
 	 */
 	public function addRule(
@@ -411,6 +416,7 @@ public function addRule(
 
 	/**
 	 * Adds a validation condition a returns new branch.
+	 * @param  (callable(self): bool)|string|bool  $validator
 	 */
 	public function addCondition($validator, $value = null): Rules
 	{
@@ -420,6 +426,7 @@ public function addCondition($validator, $value = null): Rules
 
 	/**
 	 * Adds a validation condition based on another control a returns new branch.
+	 * @param  (callable(self): bool)|string  $validator
 	 */
 	public function addConditionOn(Control $control, $validator, $value = null): Rules
 	{
@@ -429,6 +436,7 @@ public function addConditionOn(Control $control, $validator, $value = null): Rul
 
 	/**
 	 * Adds an input filter callback.
+	 * @param callable(mixed): mixed  $filter
 	 */
 	public function addFilter(callable $filter): static
 	{
@@ -496,6 +504,7 @@ public function getError(): ?string
 
 	/**
 	 * Returns errors corresponding to control.
+	 * @return string[]
 	 */
 	public function getErrors(): array
 	{
@@ -548,6 +557,7 @@ public function getOption($key): mixed
 
 	/**
 	 * Returns user-specific options.
+	 * @return array<string, mixed>
 	 */
 	public function getOptions(): array
 	{
@@ -558,6 +568,7 @@ public function getOptions(): array
 	/********************* extension methods ****************d*g**/
 
 
+	/** @param mixed[] $args */
 	public function __call(string $name, array $args)
 	{
 		$class = static::class;

src/Forms/Controls/CheckboxList.php

@@ -29,6 +29,7 @@ class CheckboxList extends MultiChoiceControl
 	protected Html $itemLabel;
 
 
+	/** @param  ?mixed[]  $items */
 	public function __construct(string|Stringable|null $label = null, ?array $items = null)
 	{
 		parent::__construct($label, $items);