From c7ed6a2b6ee2acd317d205864e9bff2be7f57102 Mon Sep 17 00:00:00 2001
From: Pol Dellaiera <pol.dellaiera@protonmail.com>
Date: Sat, 14 Dec 2019 10:43:14 +0100
Subject: [PATCH] Update phpdoc to fix PHPStan errors.

---
 grumphp.yml.dist                     |  1 +
 phpstan.neon                         |  5 +++++
 src/Builder/BuilderInterface.php     |  2 +-
 src/Exporter/Ascii.php               |  2 +-
 src/Exporter/Graph.php               |  3 +--
 src/Exporter/Gv.php                  |  8 ++++----
 src/Importer/SimpleArray.php         |  2 +-
 src/Importer/Text.php                |  6 +++---
 src/Node/AttributeNode.php           |  2 +-
 src/Node/AttributeNodeInterface.php  |  4 ++--
 src/Node/MerkleNode.php              |  2 +-
 src/Node/Node.php                    | 21 +++++++++++++++------
 src/Node/NodeInterface.php           | 11 +++++++----
 src/Node/TrieNode.php                |  2 +-
 src/Storage/NodeStorageInterface.php |  2 +-
 src/Storage/Storage.php              | 25 ++++++++++++++++++-------
 src/Storage/StorageInterface.php     |  2 +-
 src/Traverser/InOrder.php            |  4 +++-
 src/Traverser/PostOrder.php          |  4 +++-
 src/Traverser/PreOrder.php           |  4 +++-
 src/Traverser/TraverserInterface.php |  2 +-
 21 files changed, 74 insertions(+), 40 deletions(-)
 create mode 100644 phpstan.neon

diff --git a/grumphp.yml.dist b/grumphp.yml.dist
index 7db17aa..f6fe3c7 100644
--- a/grumphp.yml.dist
+++ b/grumphp.yml.dist
@@ -2,6 +2,7 @@ imports:
   - { resource: vendor/drupol/php-conventions/config/php71/grumphp.yml }
 
 parameters:
+  tasks.phpstan.config: phpstan.neon
   extra_tasks:
     phpspec:
       verbose: true
diff --git a/phpstan.neon b/phpstan.neon
new file mode 100644
index 0000000..46f091f
--- /dev/null
+++ b/phpstan.neon
@@ -0,0 +1,5 @@
+parameters:
+    checkMissingIterableValueType: false
+    ignoreErrors:
+        - '#Method drupol\\phptree\\Node\\MerkleNode::normalize\(\) should return drupol\\phptree\\Node\\MerkleNodeInterface but returns drupol\\phptree\\Node\\NodeInterface.#'
+        - '#Anonymous function should return drupol\\phptree\\Node\\MerkleNodeInterface but returns drupol\\phptree\\Node\\NodeInterface.#'
diff --git a/src/Builder/BuilderInterface.php b/src/Builder/BuilderInterface.php
index 728fdeb..2ada5ba 100644
--- a/src/Builder/BuilderInterface.php
+++ b/src/Builder/BuilderInterface.php
@@ -12,7 +12,7 @@
 interface BuilderInterface
 {
     /**
-     * @param iterable<NodeInterface> $nodes
+     * @param iterable<mixed> $nodes
      *
      * @return \drupol\phptree\Node\NodeInterface|null
      */
diff --git a/src/Exporter/Ascii.php b/src/Exporter/Ascii.php
index 515bc3d..29346e1 100644
--- a/src/Exporter/Ascii.php
+++ b/src/Exporter/Ascii.php
@@ -57,7 +57,7 @@ public function export(NodeInterface $node): string
      * @param \drupol\phptree\Node\NodeInterface $node
      *   The node
      *
-     * @return array
+     * @return array<int, mixed>
      *   The tree exported into an array
      */
     private function doExportAsArray(NodeInterface $node): array
diff --git a/src/Exporter/Graph.php b/src/Exporter/Graph.php
index b27f209..5ba8ba4 100644
--- a/src/Exporter/Graph.php
+++ b/src/Exporter/Graph.php
@@ -29,7 +29,6 @@ public function export(NodeInterface $node): OriginalGraph
         $this->graph = new OriginalGraph();
 
         foreach ($node->all() as $node_visited) {
-            /** @var int $vertexId */
             $vertexFrom = $this->createVertex($node_visited);
 
             foreach ($node_visited->children() as $child) {
@@ -65,7 +64,7 @@ protected function createVertex(NodeInterface $node): Vertex
 
             if ($node instanceof AttributeNodeInterface) {
                 foreach ($node->getAttributes() as $key => $value) {
-                    $vertex->setAttribute($key, $value);
+                    $vertex->setAttribute((string) $key, $value);
                 }
             }
         }
diff --git a/src/Exporter/Gv.php b/src/Exporter/Gv.php
index 25886ff..845b6ef 100644
--- a/src/Exporter/Gv.php
+++ b/src/Exporter/Gv.php
@@ -114,7 +114,7 @@ public function setDirected(bool $directed = true): self
     /**
      * Set the graph attributes.
      *
-     * @param array $attributes
+     * @param array<mixed, mixed> $attributes
      *   The graph attributes.
      *
      * @return \drupol\phptree\Exporter\Gv
@@ -130,7 +130,7 @@ public function setGraphAttributes(array $attributes): self
     /**
      * Converts an attributes array to string.
      *
-     * @param array $attributes
+     * @param array<mixed, mixed> $attributes
      *   The attributes.
      *
      * @return string
@@ -155,7 +155,7 @@ static function ($key, $value) {
      * @param \drupol\phptree\Node\NodeInterface $node
      *   The root node.
      *
-     * @return Generator
+     * @return Generator<NodeInterface, NodeInterface>
      *   Yield the parent and child node.
      */
     protected function findEdges(NodeInterface $node): iterable
@@ -218,7 +218,7 @@ protected function getHash(NodeInterface $node): string
      * @param \drupol\phptree\Node\NodeInterface $node
      *   The node interface.
      *
-     * @return array
+     * @return array<mixed, mixed>
      *   The attributes as an array.
      */
     protected function getNodeAttributes(NodeInterface $node): array
diff --git a/src/Importer/SimpleArray.php b/src/Importer/SimpleArray.php
index 7faaa4b..0d516de 100644
--- a/src/Importer/SimpleArray.php
+++ b/src/Importer/SimpleArray.php
@@ -23,7 +23,7 @@ public function import($data): NodeInterface
     /**
      * Convert an array into a tree.
      *
-     * @param array $data
+     * @param array<string, mixed> $data
      *
      * @return \drupol\phptree\Node\NodeInterface
      *   The tree
diff --git a/src/Importer/Text.php b/src/Importer/Text.php
index 9569039..4af16c2 100644
--- a/src/Importer/Text.php
+++ b/src/Importer/Text.php
@@ -33,7 +33,7 @@ public function import($data): NodeInterface
      * @param mixed $arguments
      *   The arguments
      *
-     * @return \drupol\phptree\Node\Node
+     * @return \drupol\phptree\Node\NodeInterface
      *   The node
      */
     protected function createNode($arguments): NodeInterface
@@ -47,10 +47,10 @@ protected function createNode($arguments): NodeInterface
      * @param string $subject
      *   The subject string
      *
-     * @return array|bool
+     * @return array<int, mixed>
      *   The array
      */
-    private function parse(string $subject)
+    private function parse(string $subject): array
     {
         $result = [];
 
diff --git a/src/Node/AttributeNode.php b/src/Node/AttributeNode.php
index e5bc319..77953c9 100644
--- a/src/Node/AttributeNode.php
+++ b/src/Node/AttributeNode.php
@@ -16,7 +16,7 @@ class AttributeNode extends NaryNode implements AttributeNodeInterface
     /**
      * ValueNode constructor.
      *
-     * @param array $attributes
+     * @param array<int|string, mixed> $attributes
      * @param int|null $capacity
      * @param \drupol\phptree\Traverser\TraverserInterface|null $traverser
      * @param \drupol\phptree\Node\NodeInterface|null $parent
diff --git a/src/Node/AttributeNodeInterface.php b/src/Node/AttributeNodeInterface.php
index 06f4c40..30361fd 100644
--- a/src/Node/AttributeNodeInterface.php
+++ b/src/Node/AttributeNodeInterface.php
@@ -24,7 +24,7 @@ public function getAttribute(string $key);
     /**
      * Get the attributes.
      *
-     * @return Traversable
+     * @return Traversable<int|string, mixed>
      *   The attributes.
      */
     public function getAttributes(): Traversable;
@@ -45,7 +45,7 @@ public function setAttribute(string $key, $value): AttributeNodeInterface;
     /**
      * Set the attributes.
      *
-     * @param Traversable $attributes
+     * @param Traversable<int|string, mixed> $attributes
      *   The attributes.
      *
      * @return \drupol\phptree\Node\AttributeNodeInterface
diff --git a/src/Node/MerkleNode.php b/src/Node/MerkleNode.php
index 724a320..347e801 100644
--- a/src/Node/MerkleNode.php
+++ b/src/Node/MerkleNode.php
@@ -65,7 +65,7 @@ public function normalize(): MerkleNodeInterface
     {
         return array_reduce(
             $this->modifiers,
-            static function (NodeInterface $tree, ModifierInterface $modifier): NodeInterface {
+            static function (MerkleNodeInterface $tree, ModifierInterface $modifier): MerkleNodeInterface {
                 return $modifier->modify($tree);
             },
             $this->clone()
diff --git a/src/Node/Node.php b/src/Node/Node.php
index 025c714..8aa06bc 100644
--- a/src/Node/Node.php
+++ b/src/Node/Node.php
@@ -164,7 +164,7 @@ public function getAncestors(): Traversable
     }
 
     /**
-     * {@inheritdoc}
+     * @return Traversable<\drupol\phptree\Node\NodeInterface>
      */
     public function getIterator()
     {
@@ -244,7 +244,9 @@ public function level(int $level): Traversable
     }
 
     /**
-     * {@inheritdoc}
+     * @param mixed $offset
+     *
+     * @return bool
      */
     public function offsetExists($offset)
     {
@@ -252,7 +254,9 @@ public function offsetExists($offset)
     }
 
     /**
-     * {@inheritdoc}
+     * @param mixed $offset
+     *
+     * @return \drupol\phptree\Node\NodeInterface
      */
     public function offsetGet($offset)
     {
@@ -260,7 +264,10 @@ public function offsetGet($offset)
     }
 
     /**
-     * {@inheritdoc}
+     * @param mixed $offset
+     * @param mixed $value
+     *
+     * @return void
      */
     public function offsetSet($offset, $value): void
     {
@@ -275,9 +282,11 @@ public function offsetSet($offset, $value): void
     }
 
     /**
-     * {@inheritdoc}
+     * @param mixed $offset
+     *
+     * @return void
      */
-    public function offsetUnset($offset): void
+    public function offsetUnset($offset)
     {
         $this->storage()->getChildren()->offsetUnset($offset);
     }
diff --git a/src/Node/NodeInterface.php b/src/Node/NodeInterface.php
index 4766b3a..f86dac6 100644
--- a/src/Node/NodeInterface.php
+++ b/src/Node/NodeInterface.php
@@ -11,6 +11,9 @@
 
 /**
  * Interface NodeInterface.
+ *
+ * @template-extends ArrayAccess<int, mixed>
+ * @template-extends IteratorAggregate<int, mixed>
  */
 interface NodeInterface extends ArrayAccess, Countable, IteratorAggregate
 {
@@ -28,7 +31,7 @@ public function add(NodeInterface ...$node): NodeInterface;
     /**
      * Get all the nodes of a tree including the parent node itself.
      *
-     * @return Traversable
+     * @return Traversable<\drupol\phptree\Node\NodeInterface>
      *   The node.
      */
     public function all(): Traversable;
@@ -36,7 +39,7 @@ public function all(): Traversable;
     /**
      * Get the children.
      *
-     * @return Traversable
+     * @return Traversable<\drupol\phptree\Node\NodeInterface>
      *   The children
      */
     public function children(): Traversable;
@@ -90,7 +93,7 @@ public function find(NodeInterface $node): ?NodeInterface;
     /**
      * Get the ancestors of a node.
      *
-     * @return Traversable
+     * @return Traversable<\drupol\phptree\Node\NodeInterface>
      *   The ancestors
      */
     public function getAncestors(): Traversable;
@@ -106,7 +109,7 @@ public function getParent(): ?NodeInterface;
     /**
      * Get the node's sibblings.
      *
-     * @return Traversable
+     * @return Traversable<\drupol\phptree\Node\NodeInterface>
      *   The sibblings
      */
     public function getSibblings(): Traversable;
diff --git a/src/Node/TrieNode.php b/src/Node/TrieNode.php
index 10ef4ca..314face 100644
--- a/src/Node/TrieNode.php
+++ b/src/Node/TrieNode.php
@@ -16,7 +16,6 @@ class TrieNode extends KeyValueNode
      */
     public function add(NodeInterface ...$nodes): NodeInterface
     {
-        /** @var \drupol\phptree\Node\KeyValueNodeInterface $node */
         foreach ($nodes as $node) {
             $data = $node->getValue();
 
@@ -32,6 +31,7 @@ public function add(NodeInterface ...$nodes): NodeInterface
             } else {
                 $nodes = [$node->getValue()];
 
+                /** @var \drupol\phptree\Node\KeyValueNodeInterface $ancestor */
                 foreach ($node->getAncestors() as $ancestor) {
                     $nodes[] = $ancestor->getValue();
                 }
diff --git a/src/Storage/NodeStorageInterface.php b/src/Storage/NodeStorageInterface.php
index f260c16..ed23e0c 100644
--- a/src/Storage/NodeStorageInterface.php
+++ b/src/Storage/NodeStorageInterface.php
@@ -12,7 +12,7 @@ interface NodeStorageInterface extends StorageInterface
     /**
      * Get the children.
      *
-     * @return ArrayObject
+     * @return ArrayObject<int, NodeInterface>
      */
     public function getChildren();
 
diff --git a/src/Storage/Storage.php b/src/Storage/Storage.php
index 5140d88..41c6ad2 100644
--- a/src/Storage/Storage.php
+++ b/src/Storage/Storage.php
@@ -12,11 +12,13 @@
  * Class Storage.
  *
  * @internal
+ *
+ * @implements ArrayAccess<string, mixed>
  */
 abstract class Storage implements ArrayAccess, StorageInterface
 {
     /**
-     * @var ArrayObject
+     * @var ArrayObject<string, mixed>
      */
     private $storage;
 
@@ -56,7 +58,9 @@ public function get($key)
     }
 
     /**
-     * {@inheritdoc}
+     * @param mixed $offset
+     *
+     * @return bool
      */
     public function offsetExists($offset)
     {
@@ -64,7 +68,9 @@ public function offsetExists($offset)
     }
 
     /**
-     * {@inheritdoc}
+     * @param mixed $offset
+     *
+     * @return mixed
      */
     public function offsetGet($offset)
     {
@@ -72,17 +78,22 @@ public function offsetGet($offset)
     }
 
     /**
-     * {@inheritdoc}
+     * @param mixed $offset
+     * @param mixed $value
+     *
+     * @return void
      */
-    public function offsetSet($offset, $value): void
+    public function offsetSet($offset, $value)
     {
         $this->storage->offsetSet($offset, $value);
     }
 
     /**
-     * {@inheritdoc}
+     * @param mixed $offset
+     *
+     * @return void
      */
-    public function offsetUnset($offset): void
+    public function offsetUnset($offset)
     {
         $this->storage->offsetUnset($offset);
     }
diff --git a/src/Storage/StorageInterface.php b/src/Storage/StorageInterface.php
index e30f3cb..da93776 100644
--- a/src/Storage/StorageInterface.php
+++ b/src/Storage/StorageInterface.php
@@ -30,5 +30,5 @@ public function get($key);
      *
      * @return StorageInterface
      */
-    public function set($key, $value): self;
+    public function set($key, $value): StorageInterface;
 }
diff --git a/src/Traverser/InOrder.php b/src/Traverser/InOrder.php
index 288b366..b36a909 100644
--- a/src/Traverser/InOrder.php
+++ b/src/Traverser/InOrder.php
@@ -28,7 +28,9 @@ public function traverse(NodeInterface $node): Traversable
     }
 
     /**
-     * {@inheritdoc}
+     * @param NodeInterface $node
+     *
+     * @return Traversable<NodeInterface>
      */
     private function doTraverse(NodeInterface $node): Traversable
     {
diff --git a/src/Traverser/PostOrder.php b/src/Traverser/PostOrder.php
index a5b2515..8004a87 100644
--- a/src/Traverser/PostOrder.php
+++ b/src/Traverser/PostOrder.php
@@ -28,7 +28,9 @@ public function traverse(NodeInterface $node): Traversable
     }
 
     /**
-     * {@inheritdoc}
+     * @param NodeInterface $node
+     *
+     * @return Traversable<NodeInterface>
      */
     private function doTraverse(NodeInterface $node): Traversable
     {
diff --git a/src/Traverser/PreOrder.php b/src/Traverser/PreOrder.php
index 698c81d..378799a 100644
--- a/src/Traverser/PreOrder.php
+++ b/src/Traverser/PreOrder.php
@@ -28,7 +28,9 @@ public function traverse(NodeInterface $node): Traversable
     }
 
     /**
-     * {@inheritdoc}
+     * @param NodeInterface $node
+     *
+     * @return Traversable<NodeInterface>
      */
     private function doTraverse(NodeInterface $node): Traversable
     {
diff --git a/src/Traverser/TraverserInterface.php b/src/Traverser/TraverserInterface.php
index 8dff5ef..b5deb69 100644
--- a/src/Traverser/TraverserInterface.php
+++ b/src/Traverser/TraverserInterface.php
@@ -19,7 +19,7 @@ interface TraverserInterface
      * @param \drupol\phptree\Node\NodeInterface $node
      *   The node
      *
-     * @return Generator|NodeInterface[]|Traversable
+     * @return Generator|Traversable<NodeInterface>
      */
     public function traverse(NodeInterface $node): Traversable;
 }