improved type annotations (#290)

Author: xificurk

src/Utils/ArrayHash.php

@@ -15,6 +15,8 @@
 /**
  * Provides objects to work as array.
  * @template T
+ * @implements \RecursiveArrayIterator<array-key, T>
+ * @implements \ArrayAccess<array-key, T>
  */
 class ArrayHash extends \stdClass implements \ArrayAccess, \Countable, \IteratorAggregate
 {
@@ -57,7 +59,7 @@ public function count(): int
 
 	/**
 	 * Replaces or appends a item.
-	 * @param  string|int  $key
+	 * @param  array-key  $key
 	 * @param  T  $value
 	 */
 	public function offsetSet($key, $value): void
@@ -72,7 +74,7 @@ public function offsetSet($key, $value): void
 
 	/**
 	 * Returns a item.
-	 * @param  string|int  $key
+	 * @param  array-key  $key
 	 * @return T
 	 */
 	#[\ReturnTypeWillChange]
@@ -84,7 +86,7 @@ public function offsetGet($key)
 
 	/**
 	 * Determines whether a item exists.
-	 * @param  string|int  $key
+	 * @param  array-key  $key
 	 */
 	public function offsetExists($key): bool
 	{
@@ -94,7 +96,7 @@ public function offsetExists($key): bool
 
 	/**
 	 * Removes the element from this list.
-	 * @param  string|int  $key
+	 * @param  array-key  $key
 	 */
 	public function offsetUnset($key): void
 	{

src/Utils/ArrayList.php

@@ -15,6 +15,8 @@
 /**
  * Provides the base class for a generic list (items can be accessed by index).
  * @template T
+ * @implements \IteratorAggregate<int, T>
+ * @implements \ArrayAccess<int, T>
  */
 class ArrayList implements \ArrayAccess, \Countable, \IteratorAggregate
 {
@@ -26,7 +28,7 @@ class ArrayList implements \ArrayAccess, \Countable, \IteratorAggregate
 
 	/**
 	 * Transforms array to ArrayList.
-	 * @param  array<T>  $array
+	 * @param  list<T>  $array
 	 * @return static
 	 */
 	public static function from(array $array)

src/Utils/Image.php

@@ -90,8 +90,8 @@
  * @method void stringUp($font, $x, $y, string $s, $col)
  * @method void trueColorToPalette(bool $dither, $ncolors)
  * @method array ttfText($size, $angle, $x, $y, $color, string $fontfile, string $text)
- * @property-read int $width
- * @property-read int $height
+ * @property-read positive-int $width
+ * @property-read positive-int $height
  * @property-read resource|\GdImage $imageResource
  */
 class Image
@@ -205,6 +205,8 @@ private static function invokeSafe(string $func, string $arg, string $message, s
 
 	/**
 	 * Creates a new true color image of the given dimensions. The default color is black.
+	 * @param  positive-int  $width
+	 * @param  positive-int  $height
 	 * @return static
 	 * @throws Nette\NotSupportedException if gd extension is not loaded
 	 */
@@ -301,6 +303,7 @@ public function __construct($image)
 
 	/**
 	 * Returns image width.
+	 * @return positive-int
 	 */
 	public function getWidth(): int
 	{
@@ -310,6 +313,7 @@ public function getWidth(): int
 
 	/**
 	 * Returns image height.
+	 * @return positive-int
 	 */
 	public function getHeight(): int
 	{
@@ -536,7 +540,7 @@ public function sharpen()
 	 * Puts another image into this image.
 	 * @param  int|string  $left in pixels or percent
 	 * @param  int|string  $top in pixels or percent
-	 * @param  int  $opacity 0..100
+	 * @param  int<0, 100>  $opacity 0..100
 	 * @return static
 	 */
 	public function place(self $image, $left = 0, $top = 0, int $opacity = 100)

src/Utils/Paginator.php

@@ -18,17 +18,17 @@
  * @property   int $page
  * @property-read int $firstPage
  * @property-read int|null $lastPage
- * @property-read int $firstItemOnPage
- * @property-read int $lastItemOnPage
+ * @property-read int<0,max> $firstItemOnPage
+ * @property-read int<0,max> $lastItemOnPage
  * @property   int $base
  * @property-read bool $first
  * @property-read bool $last
- * @property-read int|null $pageCount
- * @property   int $itemsPerPage
- * @property   int|null $itemCount
- * @property-read int $offset
- * @property-read int|null $countdownOffset
- * @property-read int $length
+ * @property-read int<0,max>|null $pageCount
+ * @property   positive-int $itemsPerPage
+ * @property   int<0,max>|null $itemCount
+ * @property-read int<0,max> $offset
+ * @property-read int<0,max>|null $countdownOffset
+ * @property-read int<0,max> $length
  */
 class Paginator
 {
@@ -89,6 +89,7 @@ public function getLastPage(): ?int
 
 	/**
 	 * Returns the sequence number of the first element on the page
+	 * @return int<0, max>
 	 */
 	public function getFirstItemOnPage(): int
 	{
@@ -100,6 +101,7 @@ public function getFirstItemOnPage(): int
 
 	/**
 	 * Returns the sequence number of the last element on the page
+	 * @return int<0, max>
 	 */
 	public function getLastItemOnPage(): int
 	{
@@ -129,6 +131,7 @@ public function getBase(): int
 
 	/**
 	 * Returns zero-based page number.
+	 * @return int<0, max>
 	 */
 	protected function getPageIndex(): int
 	{
@@ -161,6 +164,7 @@ public function isLast(): bool
 
 	/**
 	 * Returns the total number of pages.
+	 * @return int<0, max>|null
 	 */
 	public function getPageCount(): ?int
 	{
@@ -183,6 +187,7 @@ public function setItemsPerPage(int $itemsPerPage)
 
 	/**
 	 * Returns the number of items to display on a single page.
+	 * @return positive-int
 	 */
 	public function getItemsPerPage(): int
 	{
@@ -203,6 +208,7 @@ public function setItemCount(?int $itemCount = null)
 
 	/**
 	 * Returns the total number of items.
+	 * @return int<0, max>|null
 	 */
 	public function getItemCount(): ?int
 	{
@@ -212,6 +218,7 @@ public function getItemCount(): ?int
 
 	/**
 	 * Returns the absolute index of the first item on current page.
+	 * @return int<0, max>
 	 */
 	public function getOffset(): int
 	{
@@ -221,6 +228,7 @@ public function getOffset(): int
 
 	/**
 	 * Returns the absolute index of the first item on current page in countdown paging.
+	 * @return int<0, max>|null
 	 */
 	public function getCountdownOffset(): ?int
 	{
@@ -232,6 +240,7 @@ public function getCountdownOffset(): ?int
 
 	/**
 	 * Returns the number of items on current page.
+	 * @return int<0, max>
 	 */
 	public function getLength(): int
 	{

src/Utils/Reflection.php

@@ -283,7 +283,7 @@ public static function expandClassName(string $name, \ReflectionClass $context):
 	}
 
 
-	/** @return array of [alias => class] */
+	/** @return array<string, class-string> of [alias => class] */
 	public static function getUseStatements(\ReflectionClass $class): array
 	{
 		if ($class->isAnonymous()) {

src/Utils/Strings.php

@@ -376,6 +376,7 @@ public static function trim(string $s, string $charlist = self::TRIM_CHARACTERS)
 
 	/**
 	 * Pads a UTF-8 string to given length by prepending the $pad string to the beginning.
+	 * @param  non-empty-string  $pad
 	 */
 	public static function padLeft(string $s, int $length, string $pad = ' '): string
 	{
@@ -387,6 +388,7 @@ public static function padLeft(string $s, int $length, string $pad = ' '): strin
 
 	/**
 	 * Pads UTF-8 string to given length by appending the $pad string to the end.
+	 * @param  non-empty-string  $pad
 	 */
 	public static function padRight(string $s, int $length, string $pad = ' '): string
 	{

src/Utils/Validators.php

@@ -284,6 +284,7 @@ public static function isMixed(): bool
 	 * Checks if a variable is a zero-based integer indexed array.
 	 * @param  mixed  $value
 	 * @deprecated  use Nette\Utils\Arrays::isList
+	 * @return ($value is list ? true : false)
 	 */
 	public static function isList($value): bool
 	{