Document boolean typed value classes and alias updates

- Enhanced API documentation for `BoolStandard`, `TrueStandard`, and `FalseStandard` with expanded descriptions, examples, and usage scenarios.
- Introduced `Boolean` alias for `BoolStandard` with updated examples and a more descriptive purpose.
- Improved clarity in factory methods and formatting helper behaviors across boolean type definitions.

Author: georgedeploy

src/Bool/Alias/Boolean.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Bool\BoolStandard;
 
 /**
+ * Alias for the generic boolean typed value.
+ *
+ * Provides the same behavior as BoolStandard while offering a more
+ * descriptive name for APIs that prefer "Boolean".
+ *
+ * Example
+ *  - $b = Boolean::fromString('true');
+ *    $b->toString(); // "true"
+ *
  * @psalm-immutable
  */
 final readonly class Boolean extends BoolStandard

src/Bool/BoolStandard.php

@@ -12,9 +12,16 @@
 use function sprintf;
 
 /**
- * Boolean value.
+ * Generic boolean typed value.
  *
- * Example "true"
+ * Wraps a native bool and provides factories from strings/ints with common
+ * true/false synonyms (case-insensitive) and convenient formatting helpers.
+ *
+ * Example
+ *  - $v = BoolStandard::fromString('yes');
+ *    $v->value(); // true
+ *  - $v = BoolStandard::fromInt(0);
+ *    $v->toString(); // "false"
  *
  * @psalm-immutable
  */

src/Bool/FalseStandard.php

@@ -14,12 +14,18 @@
 use function trim;
 
 /**
- * Represents a literal boolean false value.
+ * Literal boolean false typed value.
  *
  * Accepts common false-like representations in factories:
  *  - Strings: "false", "0", "no", "off", "n" (case-insensitive)
  *  - Ints: 0
  *
+ * Example
+ *  - $f = FalseStandard::fromString('Off');
+ *    $f->value(); // false
+ *  - $f = FalseStandard::fromInt(0);
+ *    $f->toString(); // "false"
+ *
  * @psalm-immutable
  */
 readonly class FalseStandard extends BoolType

src/Bool/TrueStandard.php

@@ -14,12 +14,18 @@
 use function trim;
 
 /**
- * Represents a literal boolean true value.
+ * Literal boolean true typed value.
  *
  * Accepts common true-like representations in factories:
  *  - Strings: "true", "1", "yes", "on", "y" (case-insensitive)
  *  - Ints: 1
  *
+ * Example
+ *  - $t = TrueStandard::fromString('YES');
+ *    $t->value(); // true
+ *  - $t = TrueStandard::fromInt(1);
+ *    (string) $t; // "true"
+ *
  * @psalm-immutable
  */
 readonly class TrueStandard extends BoolType