Add usage examples to inline documentation for ArrayOfStrings, OptionalFail, EarlyFail, and LateFail classes

Author: georgedeploy

src/Usage/Example/ArrayOfStrings.php

@@ -19,6 +19,13 @@
  * items via `value()`, supports iteration, and can be converted to a plain
  * array or JSON.
  *
+ * Example
+ *  - $a = ArrayOfStrings::fromArray(['foo', 'bar']);
+ *    $a->toArray(); // ['foo', 'bar']
+ *    foreach ($a as $item) { $item->toString(); // 'foo', then 'bar' }
+ *  - ArrayOfStrings::fromArray([]); // throws TypeException('Expected non-empty array')
+ *  - ArrayOfStrings::fromArray([123, 45.6]); // casts to strings → ['123', '45.6']
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues

src/Usage/Example/EarlyFail.php

@@ -19,6 +19,13 @@
  * All fields must be valid on creation time. Any invalid input immediately
  * raises a domain exception from the underlying typed values.
  *
+ * Example
+ *  - $p = EarlyFail::fromScalars(id: 1, firstName: 'Alice', height: 170.5);
+ *    $p->getFirstName()->toString(); // 'Alice'
+ *  - EarlyFail::fromScalars(id: 0, firstName: 'Alice', height: 170); // throws IntegerTypeException
+ *  - EarlyFail::fromScalars(id: 1, firstName: '', height: 170); // throws StringTypeException
+ *  - EarlyFail::fromScalars(id: 1, firstName: 'Alice', height: -1); // throws FloatTypeException
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues

src/Usage/Example/LateFail.php

@@ -19,6 +19,13 @@
  * - `firstName` and `height` accept mixed inputs and may become `Undefined`;
  *   accessing their string/primitive values may fail later.
  *
+ * Example
+ *  - $p = LateFail::fromScalars(id: 1, firstName: 'Bob', height: '170.5');
+ *    $p->getHeight()->toString(); // '170.5'
+ *  - $p = LateFail::fromScalars(id: 1, firstName: '', height: null);
+ *    $p->getFirstName()->toString(); // late fail (UndefinedTypeException)
+ *    $p->getHeight()->toString(); // late fail (UndefinedTypeException)
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues

src/Usage/Example/OptionalFail.php

@@ -22,6 +22,13 @@
  * - `firstName` uses `tryFromMixed` and may be `Undefined` (late fail on access).
  * - `height` fails early only when provided; `null` becomes `Undefined` (late fail).
  *
+ * Example
+ *  - $p = OptionalFail::fromScalars(id: 1, firstName: 'Alice', height: 170);
+ *    $p->jsonSerialize(); // ['id' => '1', 'firstName' => 'Alice', 'height' => '170']
+ *  - $p = OptionalFail::fromScalars(id: 1, firstName: '', height: null);
+ *    $p->getFirstName()->toString(); // late fail (UndefinedTypeException)
+ *    $p->getHeight()->toString(); // late fail (UndefinedTypeException)
+ *
  * @internal
  *
  * @psalm-internal PhpTypedValues