Expand API documentation for integer-typed value classes and aliases

- Enhanced documentation for `IntegerStandard`, `IntegerNonNegative`, `IntegerPositive`, `IntegerWeekDay`, `IntegerTiny`, and other integer classes, clarifying behavior, validation, and formatting.
- Documented aliases including `Positive`, `NonNegative`, `IntType`, `Id`, `Tiny`, and `Integer`, with updated examples demonstrating usage and purpose.
- Improved clarity around factory methods, validation mechanisms, and example scenarios across integer type definitions.
- Standardized descriptions for range-specific and domain-specific integer implementations.

Author: georgedeploy

src/Integer/Alias/Id.php

@@ -7,9 +7,17 @@
 use PhpTypedValues\Integer\IntegerPositive;
 
 /**
- * Alias of Positive integer used as identifier.
+ * Alias for positive integer used as identifier.
  *
- * Example "42"
+ * Provides the same behavior as IntegerPositive but conveys the semantic
+ * meaning of an application-level identifier. Useful where IDs are strictly
+ * positive integers.
+ *
+ * Example
+ *  - $id = Id::fromString('42');
+ *    $id->value(); // 42
+ *  - $id = Id::fromInt(7);
+ *    (string) $id; // "7"
  *
  * @psalm-immutable
  */

src/Integer/Alias/IntType.php

@@ -7,6 +7,17 @@
 use PhpTypedValues\Integer\IntegerStandard;
 
 /**
+ * Alias for the generic integer-typed value.
+ *
+ * Provides the same behavior as IntegerStandard while offering a more
+ * descriptive name for APIs that prefer "IntType".
+ *
+ * Example
+ *  - $v = IntType::fromString('7');
+ *    $v->toString(); // "7"
+ *  - $v = IntType::fromInt(42);
+ *    (string) $v; // "42"
+ *
  * @psalm-immutable
  */
 readonly class IntType extends IntegerStandard

src/Integer/Alias/Integer.php

@@ -7,6 +7,17 @@
 use PhpTypedValues\Integer\IntegerStandard;
 
 /**
+ * Alias for the generic integer-typed value.
+ *
+ * Provides the same behavior as IntegerStandard while offering a concise
+ * descriptive name for APIs that prefer "Integer".
+ *
+ * Example
+ *  - $v = Integer::fromString('7');
+ *    $v->toString(); // "7"
+ *  - $v = Integer::fromInt(42);
+ *    (string) $v; // "42"
+ *
  * @psalm-immutable
  */
 readonly class Integer extends IntegerStandard

src/Integer/Alias/MariaDb/Tiny.php

@@ -7,9 +7,16 @@
 use PhpTypedValues\Integer\MariaDb\IntegerTiny;
 
 /**
- * Alias of IntTiny.
+ * Alias for MariaDB tiny integer type (signed TINYINT: -128..127).
  *
- * Example "1"
+ * Provides the same behavior as IntegerTiny while exposing a concise name
+ * suitable for APIs that prefer "Tiny" in the MariaDB namespace.
+ *
+ * Example
+ *  - $v = Tiny::fromInt(1);
+ *    $v->value(); // 1
+ *  - $v = Tiny::fromString('-5');
+ *    (string) $v; // "-5"
  *
  * @psalm-immutable
  */

src/Integer/Alias/NonNegative.php

@@ -7,9 +7,16 @@
 use PhpTypedValues\Integer\IntegerNonNegative;
 
 /**
- * Alias of Non-negative integer (>= 0).
+ * Alias for non‑negative integer (>= 0).
  *
- * Example "0"
+ * Provides the same behavior as IntegerNonNegative while exposing a concise
+ * name suitable for APIs that prefer "NonNegative".
+ *
+ * Example
+ *  - $v = NonNegative::fromString('0');
+ *    $v->value(); // 0
+ *  - $v = NonNegative::fromInt(10);
+ *    (string) $v; // "10"
  *
  * @psalm-immutable
  */

src/Integer/Alias/Positive.php

@@ -7,9 +7,16 @@
 use PhpTypedValues\Integer\IntegerPositive;
 
 /**
- * Alias of Positive integer (> 0).
+ * Alias for positive integer (> 0).
  *
- * Example "1"
+ * Provides the same behavior as IntegerPositive while exposing a concise
+ * name suitable for APIs that prefer "Positive".
+ *
+ * Example
+ *  - $v = Positive::fromString('1');
+ *    $v->value(); // 1
+ *  - $v = Positive::fromInt(5);
+ *    (string) $v; // "5"
  *
  * @psalm-immutable
  */

src/Integer/IntegerNonNegative.php

@@ -12,9 +12,16 @@
 use function sprintf;
 
 /**
- * Non-negative integer (>= 0).
+ * Non‑negative integer (>= 0).
  *
- * Example "0"
+ * Guarantees the wrapped integer is zero or positive. Provides factories from
+ * strictly validated string and native int, along with standard formatting.
+ *
+ * Example
+ *  - $v = IntegerNonNegative::fromString('0');
+ *    $v->value(); // 0 (int)
+ *  - $v = IntegerNonNegative::fromInt(10);
+ *    (string) $v; // "10"
  *
  * @psalm-immutable
  */

src/Integer/IntegerPositive.php

@@ -14,7 +14,14 @@
 /**
  * Positive integer (> 0).
  *
- * Example "1"
+ * Ensures the wrapped value is strictly greater than zero. Provides factories
+ * from strictly validated string and native int, plus convenient formatting.
+ *
+ * Example
+ *  - $v = IntegerPositive::fromString('1');
+ *    $v->value(); // 1 (int)
+ *  - $v = IntegerPositive::fromInt(5);
+ *    (string) $v; // "5"
  *
  * @psalm-immutable
  */

src/Integer/IntegerStandard.php

@@ -10,9 +10,16 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
- * Represents any PHP integer.
+ * Generic integer-typed value.
  *
- * Example "-10"
+ * Wraps any PHP integer and provides factories from a strictly validated
+ * string or a native int, along with convenient string formatting.
+ *
+ * Example
+ *  - $v = IntegerStandard::fromString('-10');
+ *    $v->value(); // -10 (int)
+ *  - $v = IntegerStandard::fromInt(42);
+ *    (string) $v; // "42"
  *
  * @psalm-immutable
  */

src/Integer/IntegerWeekDay.php

@@ -14,7 +14,15 @@
 /**
  * Week day number between 1 and 7.
  *
- * Example "5"
+ * Represents an integer constrained to the inclusive range 1..7 where
+ * 1 = Monday and 7 = Sunday (or any convention your domain applies).
+ * Factories accept strictly validated strings and native ints.
+ *
+ * Example
+ *  - $v = IntegerWeekDay::fromString('5');
+ *    $v->value(); // 5
+ *  - $v = IntegerWeekDay::fromInt(1);
+ *    (string) $v; // "1"
  *
  * @psalm-immutable
  */