Update phpDoc

.github/workflows/pages.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Upload Artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: 'docs/'
+          path: 'doc/'
 
       - name: Deploy to GitHub Pages
         id: deployment

.gitignore

@@ -6,3 +6,4 @@ composer.lock
 phpcs.xml
 phpdoc.xml
 phpstan.neon
+psalm.xml

phpdoc.dist.xml

@@ -6,7 +6,7 @@
     xsi:schemaLocation="https://www.phpdoc.org https://raw.githubusercontent.com/phpDocumentor/phpDocumentor/master/data/xsd/phpdoc.xsd">
     <title>PHP Basics</title>
     <paths>
-        <output>docs</output>
+        <output>doc</output>
         <cache>.phpdoc/cache</cache>
     </paths>
     <version number="latest">

src/DataStructures/StrictList.php

@@ -48,7 +48,7 @@ use Serializable;
  * @template AllowedType of mixed
  * @extends SplDoublyLinkedList<AllowedType>
  * @implements ArrayAccess<int, AllowedType>
- * @implements Iterator<int, AllowedType>
+ * @implements Iterator<AllowedType>
  */
 class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable, Iterator, Serializable
 {
@@ -205,7 +205,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
      *
      * @throws InvalidArgumentException
      *
-     * @api
+     * @internal
      */
     public function offsetSet(mixed $offset, mixed $value): void
     {

src/DataStructures/StrictQueue.php

@@ -43,7 +43,7 @@ use Serializable;
  * @template AllowedType of mixed
  * @extends StrictList<AllowedType>
  * @implements ArrayAccess<int, AllowedType>
- * @implements Iterator<int, AllowedType>
+ * @implements Iterator<AllowedType>
  */
 class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator, Serializable
 {

src/DataStructures/StrictStack.php

@@ -43,7 +43,7 @@ use Serializable;
  * @template AllowedType of mixed
  * @extends StrictList<AllowedType>
  * @implements ArrayAccess<int, AllowedType>
- * @implements Iterator<int, AllowedType>
+ * @implements Iterator<AllowedType>
  */
 class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator, Serializable
 {

src/InterfaceTraits/ArrayAccessTrait.php

@@ -33,10 +33,8 @@ use ArrayAccess;
  *
  * @api
  *
- * @template TKey of int|string
  * @template TValue of mixed
- * @template TData of array<TKey, TValue>
- * @implements ArrayAccess<TKey, TValue>
+ * @implements ArrayAccess<array-key, TValue>
  * @phpstan-require-implements ArrayAccess
  */
 trait ArrayAccessTrait
@@ -44,18 +42,18 @@ trait ArrayAccessTrait
     /**
      * Holds the array-accessible data.
      *
-     * @var TData
+     * @var array<TValue>
      */
     protected array $data = [];
 
     /**
      * Check if the specified offset exists.
      *
-     * @param TKey $offset The offset to check for
+     * @param array-key $offset The offset to check for
      *
      * @return bool Whether the offset exists
      *
-     * @api
+     * @internal
      */
     public function offsetExists(mixed $offset): bool
     {
@@ -65,11 +63,11 @@ trait ArrayAccessTrait
     /**
      * Retrieve data at the specified offset.
      *
-     * @param TKey $offset The offset to retrieve at
+     * @param array-key $offset The offset to retrieve
      *
-     * @return ?TValue The value at the offset or NULL
+     * @return ?TValue The value at the offset or NULL if invalid
      *
-     * @api
+     * @internal
      */
     public function offsetGet(mixed $offset): mixed
     {
@@ -79,12 +77,12 @@ trait ArrayAccessTrait
     /**
      * Assign a value to the specified offset.
      *
-     * @param ?TKey $offset The offset to assign to or NULL to append
+     * @param ?array-key $offset The offset to assign to or NULL to append
      * @param TValue $value The value to set
      *
      * @return void
      *
-     * @api
+     * @internal
      */
     public function offsetSet(mixed $offset, mixed $value): void
     {
@@ -98,11 +96,11 @@ trait ArrayAccessTrait
     /**
      * Unset the specified offset.
      *
-     * @param TKey $offset The offset to unset
+     * @param array-key $offset The offset to unset
      *
      * @return void
      *
-     * @api
+     * @internal
      */
     public function offsetUnset(mixed $offset): void
     {

src/InterfaceTraits/CountableTrait.php

@@ -33,10 +33,7 @@ use Countable;
  *
  * @api
  *
- * @template TKey of int|string
  * @template TValue of mixed
- * @template TData of array<TKey, TValue>
- * @implements Countable<TValue>
  * @phpstan-require-implements Countable
  */
 trait CountableTrait
@@ -44,16 +41,16 @@ trait CountableTrait
     /**
      * Holds the countable data.
      *
-     * @var TData
+     * @var array<TValue>
      */
     protected array $data = [];
 
     /**
      * Count the data items.
      *
-     * @return int The number of data items
+     * @return int<0, max> The number of data items
      *
-     * @api
+     * @internal
      */
     public function count(): int
     {

src/InterfaceTraits/IteratorAggregateTrait.php

@@ -34,10 +34,8 @@ use IteratorAggregate;
  *
  * @api
  *
- * @template TKey of int|string
  * @template TValue of mixed
- * @template TData of array<TKey, TValue>
- * @implements IteratorAggregate<TKey, TValue>
+ * @implements IteratorAggregate<TValue>
  * @phpstan-require-implements IteratorAggregate
  */
 trait IteratorAggregateTrait
@@ -45,16 +43,16 @@ trait IteratorAggregateTrait
     /**
      * Holds the iterable data.
      *
-     * @var TData
+     * @var array<TValue>
      */
     protected array $data = [];
 
     /**
      * Retrieve an external iterator.
      *
-     * @return ArrayIterator<TKey, TValue> New array iterator for data array
+     * @return ArrayIterator<array-key, TValue> New array iterator for data array
      *
-     * @api
+     * @internal
      */
     public function getIterator(): ArrayIterator
     {

src/InterfaceTraits/IteratorTrait.php

@@ -33,10 +33,8 @@ use Iterator;
  *
  * @api
  *
- * @template TKey of int|string
  * @template TValue of mixed
- * @template TData of array<TKey, TValue>
- * @implements Iterator<TKey, TValue>
+ * @implements Iterator<TValue>
  * @phpstan-require-implements Iterator
  */
 trait IteratorTrait
@@ -44,28 +42,32 @@ trait IteratorTrait
     /**
      * Holds the iterable data.
      *
-     * @var TData
+     * @var array<TValue>
      */
     protected array $data = [];
 
     /**
      * Return the current item.
      *
-     * @return TValue|false The current item or FALSE if invalid
+     * @return ?TValue The current item or NULL if invalid
      *
-     * @api
+     * @internal
      */
     public function current(): mixed
     {
-        return current($this->data);
+        if ($this->valid()) {
+            /** @var TValue */
+            return current($this->data);
+        }
+        return null;
     }
 
     /**
      * Return the current key.
      *
-     * @return ?TKey The current key or NULL if invalid
+     * @return ?array-key The current key or NULL if invalid
      *
-     * @api
+     * @internal
      */
     public function key(): mixed
     {
@@ -77,31 +79,19 @@ trait IteratorTrait
      *
      * @return void
      *
-     * @api
+     * @internal
      */
     public function next(): void
     {
         next($this->data);
     }
 
-    /**
-     * Move back to previous item.
-     *
-     * @return void
-     *
-     * @api
-     */
-    public function prev(): void
-    {
-        prev($this->data);
-    }
-
     /**
      * Rewind the iterator to the first item.
      *
      * @return void
      *
-     * @api
+     * @internal
      */
     public function rewind(): void
     {
@@ -113,7 +103,7 @@ trait IteratorTrait
      *
      * @return bool Whether the current position is valid
      *
-     * @api
+     * @internal
      */
     public function valid(): bool
     {