Document typed value contracts and base implementations

- Added detailed API documentation to type interfaces (`IntTypeInterface`, `FloatTypeInterface`, `StrTypeInterface`, etc.) and base classes (`IntType`, `FloatType`, `StrType`, etc.).
- Improved examples showcasing factory methods, formatting helpers, and validation behaviors.
- Expanded `UndefinedType` to include new methods (`toInt`, `toFloat`) with exception handling.
- Enhanced clarity and usability of all typed value definitions across the library.

Author: georgedeploy

src/Abstract/Bool/BoolType.php

@@ -7,6 +7,16 @@
 use PhpTypedValues\Abstract\TypeInterface;
 
 /**
+ * Base implementation for boolean typed values.
+ *
+ * Provides common formatting helpers and factory methods for bool-backed
+ * value objects. Concrete boolean types extend this class and add
+ * domain-specific validation if needed.
+ *
+ * Example
+ *  - $v = MyBoolean::fromBool(true);
+ *  - $v->toString(); // "true"
+ *
  * @psalm-immutable
  */
 abstract readonly class BoolType implements TypeInterface, BoolTypeInterface

src/Abstract/Bool/BoolTypeInterface.php

@@ -7,6 +7,16 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
+ * Contract for boolean typed values.
+ *
+ * Describes the API that all bool-backed value objects must implement,
+ * including factories, accessors and formatting helpers.
+ *
+ * Example
+ *  - $v = MyBoolean::fromString('true');
+ *  - $v->value();      // true
+ *  - (string) $v;      // "true"
+ *
  * @psalm-immutable
  */
 interface BoolTypeInterface

src/Abstract/DateTime/DateTimeType.php

@@ -16,6 +16,16 @@
 use function sprintf;
 
 /**
+ * Base implementation for DateTime typed values.
+ *
+ * Provides strict parsing with detailed error aggregation, round-trip
+ * validation against the format, timezone normalization and reasonable
+ * timestamp range checks.
+ *
+ * Example
+ *  - $v = MyDateTime::fromString('2025-01-02T03:04:05+00:00');
+ *  - $v->toString(); // '2025-01-02T03:04:05+00:00'
+ *
  * @psalm-immutable
  */
 abstract readonly class DateTimeType implements TypeInterface, DateTimeTypeInterface

src/Abstract/DateTime/DateTimeTypeInterface.php

@@ -8,6 +8,16 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
+ * Contract for DateTime typed values.
+ *
+ * Declares the API for value objects backed by DateTimeImmutable, including
+ * factories from strings and native DateTime, string formatting, and
+ * a safe try-from factory returning Undefined on invalid input.
+ *
+ * Example
+ *  - $v = MyDateTime::fromDateTime(new DateTimeImmutable('2025-01-02T03:04:05+00:00'));
+ *  - $v->toString(); // '2025-01-02T03:04:05+00:00'
+ *
  * @psalm-immutable
  */
 interface DateTimeTypeInterface

src/Abstract/Float/FloatType.php

@@ -10,6 +10,16 @@
 use function sprintf;
 
 /**
+ * Base implementation for float-typed values.
+ *
+ * Provides common validation for float strings and formatting helpers for
+ * value objects backed by float primitives.
+ *
+ * Example
+ *  - $v = MyFloat::fromString('3.14');
+ *  - $v->value(); // 3.14 (float)
+ *  - (string) $v; // "3.14"
+ *
  * @psalm-immutable
  */
 abstract readonly class FloatType implements TypeInterface, FloatTypeInterface

src/Abstract/Float/FloatTypeInterface.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
+ * Contract for float-typed values.
+ *
+ * Declares the API for float-backed value objects, including creation from
+ * native float or validated string, and formatting helpers.
+ *
+ * Example
+ *  - $v = MyFloat::fromFloat(1.5);
+ *  - $v->toString(); // "1.5"
+ *
  * @psalm-immutable
  */
 interface FloatTypeInterface

src/Abstract/Integer/IntType.php

@@ -10,6 +10,16 @@
 use function sprintf;
 
 /**
+ * Base implementation for integer-typed values.
+ *
+ * Contains strict string-to-int validation and common formatting helpers
+ * for value objects backed by integer primitives.
+ *
+ * Example
+ *  - $v = MyInt::fromString('42');
+ *  - $v->value(); // 42 (int)
+ *  - (string) $v; // "42"
+ *
  * @psalm-immutable
  */
 abstract readonly class IntType implements TypeInterface, IntTypeInterface

src/Abstract/Integer/IntTypeInterface.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
+ * Contract for integer-typed values.
+ *
+ * Declares the API for int-backed value objects, including strict parsing
+ * from string/native int and formatting helpers.
+ *
+ * Example
+ *  - $v = MyInt::fromInt(7);
+ *  - $v->toString(); // "7"
+ *
  * @psalm-immutable
  */
 interface IntTypeInterface

src/Abstract/String/StrType.php

@@ -7,6 +7,16 @@
 use PhpTypedValues\Abstract\TypeInterface;
 
 /**
+ * Base implementation for string-typed values.
+ *
+ * Provides common formatting helpers for value objects backed by strings.
+ * Concrete string types extend this class and add domain-specific
+ * validation/normalization.
+ *
+ * Example
+ *  - $v = MyString::fromString('hello');
+ *  - $v->toString(); // "hello"
+ *
  * @psalm-immutable
  */
 abstract readonly class StrType implements TypeInterface, StrTypeInterface

src/Abstract/String/StrTypeInterface.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
+ * Contract for string-typed values.
+ *
+ * Declares the API for string-backed value objects, including factory
+ * methods, accessors and formatting helpers.
+ *
+ * Example
+ *  - $v = MyString::fromString('abc');
+ *  - $v->value(); // 'abc'
+ *
  * @psalm-immutable
  */
 interface StrTypeInterface