Add inline documentation to clarify purpose, usage, and behavior of ArrayOfStrings, ArrayTypeInterface, and examples

Author: georgedeploy

src/Abstract/Array/ArrayType.php

@@ -10,6 +10,10 @@
 /**
  * Base implementation for array typed values.
  *
+ * Provides an immutable, iterable, and JSON‑serializable collection of
+ * typed items. Concrete implementations define item validation and
+ * factory behavior.
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues

src/Abstract/Array/ArrayTypeInterface.php

@@ -9,23 +9,43 @@
 /**
  * Contract for array typed values.
  *
+ * Represents a read‑only collection of typed items with factory helpers
+ * to construct the collection from raw arrays. Implementations are
+ * immutable and iterable.
+ *
+ * @internal
+ *
+ * @psalm-internal PhpTypedValues
+ *
  * @template TItem
  *
  * @psalm-immutable
  */
 interface ArrayTypeInterface
 {
     /**
+     * Returns the underlying typed items.
+     *
      * @psalm-return list<TItem>
      */
     public function value(): array;
 
     /**
+     * Creates a new collection from a list of raw values.
+     * Implementations MUST fail early on invalid input.
+     *
+     * @param array $value raw input values
+     *
      * @psalm-param list<mixed> $value
      */
     public static function fromArray(array $value): static;
 
     /**
+     * Creates a new collection from a list of raw values, allowing
+     * late/optional failure semantics via `Undefined` where applicable.
+     *
+     * @param array $value raw input values
+     *
      * @psalm-param list<mixed> $value
      */
     public static function tryFromArray(array $value): static|Undefined;

src/Usage/Example/ArrayOfStrings.php

@@ -13,6 +13,12 @@
 use PhpTypedValues\String\StringNonEmpty;
 
 /**
+ * Immutable collection of non-empty strings represented as `StringNonEmpty`.
+ *
+ * Provides factory helpers to construct from raw arrays, exposes the typed
+ * items via `value()`, supports iteration, and can be converted to a plain
+ * array or JSON.
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues
@@ -24,7 +30,9 @@
 final readonly class ArrayOfStrings extends ArrayType
 {
     /**
-     * @param non-empty-list<StringNonEmpty> $value
+     * Creates a new collection from a non-empty list of `StringNonEmpty`.
+     *
+     * @param non-empty-list<StringNonEmpty> $value items must be instances of `StringNonEmpty`
      *
      * @throws StringTypeException
      * @throws TypeException
@@ -45,6 +53,11 @@ public function __construct(
     }
 
     /**
+     * Creates a collection from a non-empty list of raw values by casting each
+     * value to string and validating it as `StringNonEmpty`.
+     *
+     * @param array $value raw values to convert
+     *
      * @psalm-param list<mixed> $value
      *
      * @throws StringTypeException
@@ -66,6 +79,11 @@ public static function fromArray(array $value): static
     }
 
     /**
+     * Same as `fromArray()` but intended for scenarios where late/optional
+     * failure might be desirable. Current implementation mirrors `fromArray()`.
+     *
+     * @param array $value raw values to convert
+     *
      * @psalm-param list<mixed> $value
      *
      * @throws StringTypeException
@@ -77,6 +95,8 @@ public static function tryFromArray(array $value): static
     }
 
     /**
+     * Returns the underlying typed items.
+     *
      * @psalm-return non-empty-list<StringNonEmpty>
      */
     public function value(): array
@@ -85,6 +105,8 @@ public function value(): array
     }
 
     /**
+     * Converts the collection to a non-empty list of raw strings.
+     *
      * @return non-empty-list<non-empty-string>
      */
     public function toArray(): array
@@ -101,6 +123,8 @@ public function toArray(): array
     }
 
     /**
+     * JSON serialization proxy that returns the same as `toArray()`.
+     *
      * @return non-empty-list<non-empty-string>
      */
     public function jsonSerialize(): array
@@ -109,6 +133,8 @@ public function jsonSerialize(): array
     }
 
     /**
+     * Iterates over the underlying `StringNonEmpty` items.
+     *
      * @return Generator<int, StringNonEmpty>
      */
     public function getIterator(): Generator

src/Usage/Example/EarlyFail.php

@@ -14,6 +14,11 @@
 use PhpTypedValues\String\StringNonEmpty;
 
 /**
+ * Example of strict early‑fail semantics for constructing a composite value.
+ *
+ * All fields must be valid on creation time. Any invalid input immediately
+ * raises a domain exception from the underlying typed values.
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues
@@ -30,6 +35,12 @@ public function __construct(
     }
 
     /**
+     * Factory that validates all inputs and fails immediately on invalid data.
+     *
+     * @param int    $id        positive integer identifier
+     * @param string $firstName non-empty person name
+     * @param float  $height    positive height value
+     *
      * @throws IntegerTypeException
      * @throws FloatTypeException
      * @throws StringTypeException
@@ -46,16 +57,25 @@ public static function fromScalars(
         );
     }
 
+    /**
+     * Returns validated height value.
+     */
     public function getHeight(): FloatPositive
     {
         return $this->height;
     }
 
+    /**
+     * Returns validated identifier.
+     */
     public function getId(): IntegerPositive
     {
         return $this->id;
     }
 
+    /**
+     * Returns validated first name.
+     */
     public function getFirstName(): StringNonEmpty
     {
         return $this->firstName;

src/Usage/Example/LateFail.php

@@ -13,6 +13,12 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
+ * Example of late‑fail semantics using `Undefined` for optional/invalid inputs.
+ *
+ * - `id` must be valid at construction time (early fail).
+ * - `firstName` and `height` accept mixed inputs and may become `Undefined`;
+ *   accessing their string/primitive values may fail later.
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues
@@ -29,6 +35,14 @@ public function __construct(
     }
 
     /**
+     * Factory that validates only the strictly required field (`id`) early,
+     * while optional/mixed inputs for `firstName` and `height` may result in
+     * `Undefined` values (late‑fail on access).
+     *
+     * @param int                   $id        positive integer identifier (validated immediately)
+     * @param mixed                 $firstName non-empty string or will become `Undefined`
+     * @param string|float|int|null $height    positive numeric or `null` to become `Undefined`
+     *
      * @throws IntegerTypeException
      */
     public static function fromScalars(
@@ -43,16 +57,25 @@ public static function fromScalars(
         );
     }
 
+    /**
+     * Returns height, which may be `Undefined`.
+     */
     public function getHeight(): FloatPositive|Undefined
     {
         return $this->height;
     }
 
+    /**
+     * Returns validated identifier.
+     */
     public function getId(): IntegerPositive
     {
         return $this->id;
     }
 
+    /**
+     * Returns first name or `Undefined`.
+     */
     public function getFirstName(): StringNonEmpty|Undefined
     {
         return $this->firstName;

src/Usage/Example/OptionalFail.php

@@ -16,6 +16,12 @@
 require_once 'vendor/autoload.php';
 
 /**
+ * Example of optional/late‑fail semantics.
+ *
+ * - `id` must be valid at construction time (early fail).
+ * - `firstName` uses `tryFromMixed` and may be `Undefined` (late fail on access).
+ * - `height` fails early only when provided; `null` becomes `Undefined` (late fail).
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues
@@ -32,6 +38,12 @@ public function __construct(
     }
 
     /**
+     * Factory that supports optional and late‑fail inputs.
+     *
+     * @param int                   $id        positive integer identifier (validated immediately)
+     * @param string|null           $firstName non-empty string or empty/invalid treated as `Undefined`
+     * @param string|float|int|null $height    positive numeric value; `null` produces `Undefined`
+     *
      * @throws IntegerTypeException
      * @throws FloatTypeException
      */
@@ -49,22 +61,33 @@ public static function fromScalars(
         );
     }
 
+    /**
+     * Returns height, which may be `Undefined` when it was omitted.
+     */
     public function getHeight(): FloatPositive|Undefined
     {
         return $this->height;
     }
 
+    /**
+     * Returns validated identifier.
+     */
     public function getId(): IntegerPositive
     {
         return $this->id;
     }
 
+    /**
+     * Returns first name or `Undefined` when the input was empty/invalid.
+     */
     public function getFirstName(): StringNonEmpty|Undefined
     {
         return $this->firstName;
     }
 
     /**
+     * Serializes to an associative array of strings.
+     *
      * @throws UndefinedTypeException
      */
     public function jsonSerialize(): array

tests/Unit/Usage/Example/ArrayOfStringsTest.php

@@ -87,7 +87,7 @@
 
     $arrayOfStrings = ArrayOfStrings::fromArray($array);
 
-    $arrayOfStringsJson = json_encode($arrayOfStrings, JSON_THROW_ON_ERROR);
+    $arrayOfStringsJson = json_encode($arrayOfStrings, \JSON_THROW_ON_ERROR);
     $arrayOfStringsJsonDecoded = json_decode($arrayOfStringsJson, true);
 
     expect($arrayOfStrings->toArray())->toBe($array);