fix Psalm annotations for traits and their usages

php-ds · Jun 13, 2022 · 5d7a94e · 5d7a94e
1 parent 82927ed
commit 5d7a94e
Show file tree

Hide file tree

Showing 8 changed files with 69 additions and 27 deletions.
diff --git a/src/Deque.php b/src/Deque.php
@@ -13,6 +13,8 @@
  *
  * @template TValue
  * @implements Sequence<TValue>
+ * @template-use Traits\GenericCollection<int, TValue>
+ * @template-use Traits\GenericSequence<TValue>
  */
 final class Deque implements Sequence
 {

diff --git a/src/Map.php b/src/Map.php
@@ -16,6 +16,7 @@
  * @template TKey
  * @template TValue
  * @implements Collection<TKey, TValue>
+ * @template-use Traits\GenericCollection<TKey, TValue>
  */
 final class Map implements Collection, \ArrayAccess
 {

diff --git a/src/Queue.php b/src/Queue.php
@@ -12,6 +12,7 @@
  *
  * @template TValue
  * @implements Collection<int, TValue>
+ * @template-use Traits\GenericCollection<int, TValue>
  */
 final class Queue implements Collection, \ArrayAccess 
 {

diff --git a/src/Set.php b/src/Set.php
@@ -12,6 +12,7 @@
  *
  * @template TValue
  * @implements Collection<int, TValue>
+ * @template-use Traits\GenericCollection<int, TValue>
  */
 final class Set implements Collection, \ArrayAccess 
 {

diff --git a/src/Stack.php b/src/Stack.php
@@ -12,6 +12,7 @@
  *
  * @template TValue
  * @implements Sequence<TValue>
+ * @template-use Traits\GenericCollection<int, TValue>
  */
 final class Stack implements Collection, \ArrayAccess
 {

diff --git a/src/Traits/GenericCollection.php b/src/Traits/GenericCollection.php
@@ -3,6 +3,8 @@
 
 /**
  * Common to structures that implement the base collection interface.
+ * @template-covariant TKey
+ * @template-covariant TValue
  */
 trait GenericCollection
 {
@@ -37,6 +39,8 @@ public function jsonSerialize()
      * Creates a shallow copy of the collection.
      *
      * @return static a shallow copy of the collection.
+     *
+     * @psalm-return static<TKey, TValue>
      */
     public function copy(): self
     {
@@ -51,6 +55,8 @@ public function copy(): self
      * could not be created (for example when object are used as keys).
      *
      * @return array
+     *
+     * @psalm-return array<TKey, TValue>
      */
     abstract public function toArray(): array;
 

diff --git a/src/Traits/GenericSequence.php b/src/Traits/GenericSequence.php
@@ -11,6 +11,8 @@
  * share the same implementation using an array array.
  *
  * @package Ds\Traits
+ *
+ * @template TValue
  */
 trait GenericSequence
 {
@@ -39,15 +41,15 @@ public function __construct(iterable $values = [])
     }
 
     /**
-     * @inheritdoc
+     * @return list<TValue>
      */
     public function toArray(): array
     {
         return $this->array;
     }
 
     /**
-     * @inheritdoc
+     * @psalm-param callable(TValue): TValue $callback
      */
     public function apply(callable $callback)
     {
@@ -57,7 +59,9 @@ public function apply(callable $callback)
     }
 
     /**
-     * @inheritdoc
+     * @template TValue2
+     * @psalm-param iterable<TValue2> $values
+     * @psalm-return Sequence<TValue|TValue2>
      */
     public function merge($values): Sequence
     {
@@ -67,15 +71,15 @@ public function merge($values): Sequence
     }
 
     /**
-     * @inheritdoc
+     *
      */
     public function count(): int
     {
         return count($this->array);
     }
 
     /**
-     * @inheritDoc
+     * @psalm-param TValue ...$values
      */
     public function contains(...$values): bool
     {
@@ -89,15 +93,18 @@ public function contains(...$values): bool
     }
 
     /**
-     * @inheritDoc
+     * @psalm-param (callable(TValue): bool)|null $callback
+     * @psalm-return Sequence<TValue>
      */
     public function filter(callable $callback = null): Sequence
     {
         return new self(array_filter($this->array, $callback ?: 'boolval'));
     }
 
     /**
-     * @inheritDoc
+     * @return int|null
+     *
+     * @psalm-param TValue $value
      */
     public function find($value)
     {
@@ -107,7 +114,9 @@ public function find($value)
     }
 
     /**
-     * @inheritDoc
+     * @throws \UnderflowException if the sequence is empty.
+     *
+     * @psalm-return TValue
      */
     public function first()
     {
@@ -119,7 +128,9 @@ public function first()
     }
 
     /**
-     * @inheritDoc
+     * @throws \OutOfRangeException if the index is not in the range [0, size-1]
+     *
+     * @psalm-return TValue
      */
     public function get(int $index)
     {
@@ -131,7 +142,9 @@ public function get(int $index)
     }
 
     /**
-     * @inheritDoc
+     * @throws \OutOfRangeException if the index is not in the range [0, n]
+     *
+     * @psalm-param TValue ...$values
      */
     public function insert(int $index, ...$values)
     {
@@ -144,15 +157,17 @@ public function insert(int $index, ...$values)
     }
 
     /**
-     * @inheritDoc
+     *
      */
     public function join(string $glue = null): string
     {
         return implode($glue ?? '', $this->array);
     }
 
     /**
-     * @inheritDoc
+     * @throws \UnderflowException if the sequence is empty.
+     *
+     * @psalm-return TValue
      */
     public function last()
     {
@@ -164,15 +179,18 @@ public function last()
     }
 
     /**
-     * @inheritDoc
+     * @template TNewValue
+     * @psalm-param callable(TValue): TNewValue $callback
+     * @psalm-return Sequence<TNewValue>
      */
     public function map(callable $callback): Sequence
     {
         return new self(array_map($callback, $this->array));
     }
 
     /**
-     * @inheritDoc
+     * @throws \UnderflowException if the sequence is empty.
+     * @psalm-return TValue
      */
     public function pop()
     {
@@ -187,7 +205,7 @@ public function pop()
     }
 
     /**
-     * @inheritDoc
+     * @psalm-param TValue ...$values
      */
     public function push(...$values)
     {
@@ -199,15 +217,20 @@ public function push(...$values)
     }
 
     /**
-     * @inheritDoc
+     * @template TCarry
+     * @psalm-param callable(TCarry, TValue): TCarry $callback
+     * @psalm-param TCarry $initial
+     * @psalm-return TCarry
      */
     public function reduce(callable $callback, $initial = null)
     {
         return array_reduce($this->array, $callback, $initial);
     }
 
     /**
-     * @inheritDoc
+     * @throws \OutOfRangeException if the index is not in the range [0, size-1]
+     *
+     * @psalm-return TValue
      */
     public function remove(int $index)
     {
@@ -222,15 +245,15 @@ public function remove(int $index)
     }
 
     /**
-     * @inheritDoc
+     *
      */
     public function reverse()
     {
         $this->array = array_reverse($this->array);
     }
 
     /**
-     * @inheritDoc
+     * @psalm-return Sequence<TValue>
      */
     public function reversed(): Sequence
     {
@@ -252,7 +275,7 @@ private function normalizeRotations(int $r)
     }
 
     /**
-     * @inheritDoc
+     *
      */
     public function rotate(int $rotations)
     {
@@ -262,7 +285,9 @@ public function rotate(int $rotations)
     }
 
     /**
-     * @inheritDoc
+     * @throws \OutOfRangeException if the index is not in the range [0, size-1]
+     *
+     * @psalm-param TValue $value
      */
     public function set(int $index, $value)
     {
@@ -274,7 +299,9 @@ public function set(int $index, $value)
     }
 
     /**
-     * @inheritDoc
+     * @throws \UnderflowException if the sequence was empty.
+     *
+     * @psalm-return TValue
      */
     public function shift()
     {
@@ -289,7 +316,7 @@ public function shift()
     }
 
     /**
-     * @inheritDoc
+     * @psalm-return Sequence<TValue>
      */
     public function slice(int $offset, int $length = null): Sequence
     {
@@ -301,7 +328,7 @@ public function slice(int $offset, int $length = null): Sequence
     }
 
     /**
-     * @inheritDoc
+     * @psalm-param (callable(TValue, TValue): int)|null $comparator
      */
     public function sort(callable $comparator = null)
     {
@@ -313,7 +340,8 @@ public function sort(callable $comparator = null)
     }
 
     /**
-     * @inheritDoc
+     * @psalm-param (callable(TValue, TValue): int)|null $comparator
+     * @psalm-return Sequence<TValue>
      */
     public function sorted(callable $comparator = null): Sequence
     {
@@ -323,15 +351,15 @@ public function sorted(callable $comparator = null): Sequence
     }
 
     /**
-     * @inheritDoc
+     * @return int|float
      */
     public function sum()
     {
         return array_sum($this->array);
     }
 
     /**
-     * @inheritDoc
+     * @psalm-param TValue ...$values
      */
     public function unshift(...$values)
     {

diff --git a/src/Vector.php b/src/Vector.php
@@ -11,6 +11,8 @@
  *
  * @template TValue
  * @implements Sequence<TValue>
+ * @template-use Traits\GenericCollection<int, TValue>
+ * @template-use Traits\GenericSequence<TValue>
  */
 final class Vector implements Sequence
 {