Update phpDoc for interface traits

src/InterfaceTraits/ArrayAccessTrait.php

@@ -28,6 +28,8 @@ use ArrayAccess;
 /**
  * A generic implementation of the ArrayAccess interface.
  *
+ * Internally it accesses the protected `$_data` array.
+ *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\InterfaceTraits
  *
@@ -42,9 +44,11 @@ trait ArrayAccessTrait
     /**
      * Holds the array-accessible data.
      *
-     * @var array<TValue>
+     * @var TValue[]
+     *
+     * @internal
      */
-    protected array $data = [];
+    protected array $_data = [];
 
     /**
      * Check if the specified offset exists.
@@ -53,11 +57,11 @@ trait ArrayAccessTrait
      *
      * @return bool Whether the offset exists
      *
-     * @internal
+     * @api
      */
     public function offsetExists(mixed $offset): bool
     {
-        return isset($this->data[$offset]);
+        return isset($this->_data[$offset]);
     }
 
     /**
@@ -67,11 +71,11 @@ trait ArrayAccessTrait
      *
      * @return ?TValue The value at the offset or NULL if invalid
      *
-     * @internal
+     * @api
      */
     public function offsetGet(mixed $offset): mixed
     {
-        return $this->data[$offset] ?? null;
+        return $this->_data[$offset] ?? null;
     }
 
     /**
@@ -82,14 +86,14 @@ trait ArrayAccessTrait
      *
      * @return void
      *
-     * @internal
+     * @api
      */
     public function offsetSet(mixed $offset, mixed $value): void
     {
         if (is_null($offset)) {
-            $this->data[] = $value;
+            $this->_data[] = $value;
         } else {
-            $this->data[$offset] = $value;
+            $this->_data[$offset] = $value;
         }
     }
 
@@ -100,10 +104,10 @@ trait ArrayAccessTrait
      *
      * @return void
      *
-     * @internal
+     * @api
      */
     public function offsetUnset(mixed $offset): void
     {
-        unset($this->data[$offset]);
+        unset($this->_data[$offset]);
     }
 }

src/InterfaceTraits/CountableTrait.php

@@ -28,12 +28,15 @@ use Countable;
 /**
  * A generic implementation of the Countable interface.
  *
+ * Internally it counts the values of the protected `$_data` array.
+ *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\InterfaceTraits
  *
  * @api
  *
  * @template TValue of mixed
+ * @implements Countable
  * @phpstan-require-implements Countable
  */
 trait CountableTrait
@@ -41,19 +44,21 @@ trait CountableTrait
     /**
      * Holds the countable data.
      *
-     * @var array<TValue>
+     * @var TValue[]
+     *
+     * @internal
      */
-    protected array $data = [];
+    protected array $_data = [];
 
     /**
      * Count the data items.
      *
      * @return int<0, max> The number of data items
      *
-     * @internal
+     * @api
      */
     public function count(): int
     {
-        return count($this->data);
+        return count($this->_data);
     }
 }

src/InterfaceTraits/IteratorAggregateTrait.php

@@ -29,6 +29,8 @@ use IteratorAggregate;
 /**
  * A generic implementation of the IteratorAggregate interface.
  *
+ * Internally it iterates over the protected `$_data` array.
+ *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\InterfaceTraits
  *
@@ -43,19 +45,21 @@ trait IteratorAggregateTrait
     /**
      * Holds the iterable data.
      *
-     * @var array<TValue>
+     * @var TValue[]
+     *
+     * @internal
      */
-    protected array $data = [];
+    protected array $_data = [];
 
     /**
      * Retrieve an external iterator.
      *
-     * @return ArrayIterator<array-key, TValue> New array iterator for data array
+     * @return ArrayIterator<array-key, TValue> New iterator for the data array
      *
-     * @internal
+     * @api
      */
     public function getIterator(): ArrayIterator
     {
-        return new ArrayIterator($this->data);
+        return new ArrayIterator($this->_data);
     }
 }

src/InterfaceTraits/IteratorTrait.php

@@ -28,6 +28,8 @@ use Iterator;
 /**
  * A generic implementation of the Iterator interface.
  *
+ * Internally it iterates over the protected `$_data` array.
+ *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\InterfaceTraits
  *
@@ -42,22 +44,24 @@ trait IteratorTrait
     /**
      * Holds the iterable data.
      *
-     * @var array<TValue>
+     * @var TValue[]
+     *
+     * @internal
      */
-    protected array $data = [];
+    protected array $_data = [];
 
     /**
      * Return the current item.
      *
      * @return ?TValue The current item or NULL if invalid
      *
-     * @internal
+     * @api
      */
     public function current(): mixed
     {
         if ($this->valid()) {
             /** @var TValue */
-            return current($this->data);
+            return current($this->_data);
         }
         return null;
     }
@@ -67,11 +71,11 @@ trait IteratorTrait
      *
      * @return ?array-key The current key or NULL if invalid
      *
-     * @internal
+     * @api
      */
     public function key(): mixed
     {
-        return key($this->data);
+        return key($this->_data);
     }
 
     /**
@@ -79,11 +83,23 @@ trait IteratorTrait
      *
      * @return void
      *
-     * @internal
+     * @api
      */
     public function next(): void
     {
-        next($this->data);
+        next($this->_data);
+    }
+
+    /**
+     * Move back to previous item.
+     *
+     * @return void
+     *
+     * @api
+     */
+    public function prev(): void
+    {
+        prev($this->_data);
     }
 
     /**
@@ -91,11 +107,11 @@ trait IteratorTrait
      *
      * @return void
      *
-     * @internal
+     * @api
      */
     public function rewind(): void
     {
-        reset($this->data);
+        reset($this->_data);
     }
 
     /**
@@ -103,7 +119,7 @@ trait IteratorTrait
      *
      * @return bool Whether the current position is valid
      *
-     * @internal
+     * @api
      */
     public function valid(): bool
     {