Enhance the Undefined type documentation

Author: georgedeploy

src/Undefined/Alias/NotExist.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Undefined\UndefinedStandard;
 
 /**
+ * Implementation for a special "NotExist" typed value.
+ *
+ * Use it in APIs that must return a typed value when no meaningful value is available yet.
+ * Prefer this over null to make intent explicit and keep type-safety.
+ *
+ * Example
+ *  - return NotExist::create();
+ *  - $v->toString(); // throws UndefinedTypeException
+ *
  * @psalm-immutable
  */
 readonly class NotExist extends UndefinedStandard

src/Undefined/Alias/NotFound.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Undefined\UndefinedStandard;
 
 /**
+ * Implementation for a special "NotFound" typed value.
+ *
+ * Use it in APIs that must return a typed value when no meaningful value is available yet.
+ * Prefer this over null to make intent explicit and keep type-safety.
+ *
+ * Example
+ *  - return NotFound::create();
+ *  - $v->toString(); // throws UndefinedTypeException
+ *
  * @psalm-immutable
  */
 readonly class NotFound extends UndefinedStandard

src/Undefined/Alias/NotSet.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Undefined\UndefinedStandard;
 
 /**
+ * Implementation for a special "NotSet" typed value.
+ *
+ * Use it in APIs that must return a typed value when no meaningful value is available yet.
+ * Prefer this over null to make intent explicit and keep type-safety.
+ *
+ * Example
+ *  - return NotSet::create();
+ *  - $v->toString(); // throws UndefinedTypeException
+ *
  * @psalm-immutable
  */
 readonly class NotSet extends UndefinedStandard

src/Undefined/Alias/Undefined.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Undefined\UndefinedStandard;
 
 /**
+ * Implementation for a special "Undefined" typed value.
+ *
+ * Use it in APIs that must return a typed value when no meaningful value is available yet.
+ * Prefer this over null to make intent explicit and keep type-safety.
+ *
+ * Example
+ *  - return Undefined::create();
+ *  - $v->toString(); // throws UndefinedTypeException
+ *
  * @psalm-immutable
  */
 readonly class Undefined extends UndefinedStandard

src/Undefined/Alias/Unknown.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Undefined\UndefinedStandard;
 
 /**
+ * Implementation for a special "Unknown" typed value.
+ *
+ * Use it in APIs that must return a typed value when no meaningful value is available yet.
+ * Prefer this over null to make intent explicit and keep type-safety.
+ *
+ * Example
+ *  - return Unknown::create();
+ *  - $v->toString(); // throws UndefinedTypeException
+ *
  * @psalm-immutable
  */
 readonly class Unknown extends UndefinedStandard

src/Undefined/UndefinedStandard.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Abstract\Undefined\UndefinedType;
 
 /**
+ * Base implementation for a special "UndefinedStandard" typed value.
+ *
+ * Use it in APIs that must return a typed value when no meaningful value is available yet.
+ * Prefer this over null to make intent explicit and keep type-safety.
+ *
+ * Example
+ *  - return UndefinedStandard::create();
+ *  - $v->toString(); // throws UndefinedTypeException
+ *
  * @psalm-immutable
  */
 readonly class UndefinedStandard extends UndefinedType