Improve docblock

Author: nyamsprod

src/ByteSequenceTest.php

@@ -9,7 +9,7 @@
  */
 final class ByteSequenceTest extends StructuredFieldTest
 {
-    /** @var array|string[] */
+    /** @var array<string> */
     protected array $paths = [
         __DIR__.'/../vendor/httpwg/structured-field-tests/binary.json',
     ];

src/Dictionary.php

@@ -19,10 +19,9 @@
  * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.2
  *
  * @implements MemberOrderedMap<string, Value|InnerList<int, Value>>
- * @implements ArrayAccess<string, Value|InnerList<int, Value>>
  * @phpstan-import-type DataType from Item
  */
-final class Dictionary implements MemberOrderedMap, ArrayAccess
+final class Dictionary implements MemberOrderedMap
 {
     /** @var array<string, Value|InnerList<int, Value>> */
     private array $members = [];

src/DictionaryTest.php

@@ -9,7 +9,7 @@
 
 final class DictionaryTest extends StructuredFieldTest
 {
-    /** @var array|string[] */
+    /** @var array<string> */
     protected array $paths = [
         __DIR__.'/../vendor/httpwg/structured-field-tests/dictionary.json',
     ];

src/InnerList.php

@@ -16,11 +16,10 @@
 
 /**
  * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.1.1
- * @implements ArrayAccess<int, Value>
  * @implements MemberList<int, Value>
  * @phpstan-import-type DataType from Item
  */
-final class InnerList implements ArrayAccess, MemberList, ParameterAccess
+final class InnerList implements MemberList, ParameterAccess
 {
     /** @var list<Value> */
     private array $members;

src/ItemTest.php

@@ -14,7 +14,7 @@
  */
 final class ItemTest extends StructuredFieldTest
 {
-    /** @var array|string[] */
+    /** @var array<string> */
     protected array $paths = [
         __DIR__.'/../vendor/httpwg/structured-field-tests/boolean.json',
         __DIR__.'/../vendor/httpwg/structured-field-tests/number.json',

src/MemberContainer.php

@@ -4,16 +4,17 @@
 
 namespace Bakame\Http\StructuredFields;
 
+use ArrayAccess;
 use Countable;
-use Iterator;
 use IteratorAggregate;
 
 /**
  * @template TKey
  * @template TValue of StructuredField
+ * @template-extends ArrayAccess<TKey, TValue>
  * @template-extends IteratorAggregate<TKey, TValue>
  */
-interface MemberContainer extends Countable, IteratorAggregate, StructuredField
+interface MemberContainer extends ArrayAccess, Countable, IteratorAggregate, StructuredField
 {
     /**
      * Tells whether the instance contains no members.
@@ -25,15 +26,13 @@ public function hasNoMembers(): bool;
      */
     public function hasMembers(): bool;
 
-    /**
-     * @return Iterator<TKey, TValue>
-     */
-    public function getIterator(): Iterator;
-
     /**
      * @return TValue
      */
     public function get(string|int $offset): StructuredField;
 
+    /**
+     * Tells whether the instance contain a members at the specified offset.
+     */
     public function has(string|int $offset): bool;
 }

src/MemberList.php

@@ -13,28 +13,45 @@ interface MemberList extends MemberContainer
 {
     /**
      * Inserts members at the beginning of the list.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains the specified changes.
      */
     public function unshift(StructuredField ...$members): static;
 
     /**
      * Inserts members at the end of the list.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains the specified changes.
      */
     public function push(StructuredField ...$members): static;
 
     /**
      * Inserts members at the index.
      *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains the specified changes.
+     *
      * @throws InvalidOffset If the index does not exist
      */
     public function insert(int $index, StructuredField ...$members): static;
 
     /**
      * Replaces the member associated with the index.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains the specified changes.
+     *
+     * @throws InvalidOffset If the index does not exist
      */
     public function replace(int $index, StructuredField $member): static;
 
     /**
-     * Deletes members associated with the given indexes.
+     * Deletes members associated with the list of submitted keys.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains the specified changes.
      */
     public function remove(int ...$indexes): static;
 }

src/OrderedList.php

@@ -17,11 +17,10 @@
 use function is_array;
 
 /**
- * @implements ArrayAccess<int, Value|InnerList<int, Value>>
  * @implements MemberList<int, Value|InnerList<int, Value>>
  * @phpstan-import-type DataType from Item
  */
-final class OrderedList implements ArrayAccess, MemberList
+final class OrderedList implements MemberList
 {
     /** @var list<Value|InnerList<int, Value>> */
     private array $members;

src/Parameters.php

@@ -17,11 +17,10 @@
 
 /**
  * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.1.2
- * @implements ArrayAccess<string, Value>
  * @implements MemberOrderedMap<string, Value>
  * @phpstan-import-type DataType from Item
  */
-final class Parameters implements ArrayAccess, MemberOrderedMap
+final class Parameters implements MemberOrderedMap
 {
     /** @var array<string, Value> */
     private array $members = [];

src/ParserTest.php

@@ -8,7 +8,7 @@
 
 final class ParserTest extends StructuredFieldTest
 {
-    /** @var array|string[] */
+    /** @var array<string> */
     protected array $paths = [
         __DIR__.'/../vendor/httpwg/structured-field-tests/examples.json',
         __DIR__.'/../vendor/httpwg/structured-field-tests/key-generated.json',