Expand API documentation for float-typed value classes and aliases

- Enhanced documentation for `FloatStandard`, `FloatNonNegative`, and `FloatPositive` with detailed descriptions, examples, and usage scenarios.
- Introduced and documented aliases, including `Double`, `FloatType`, `Positive`, and `NonNegative`, with updated examples highlighting their usage and purpose.
- Improved clarity around factory methods, validation behaviors, and formatting helpers across float type definitions.

Author: georgedeploy

src/Float/Alias/Double.php

@@ -7,6 +7,17 @@
 use PhpTypedValues\Float\FloatStandard;
 
 /**
+ * Alias for the generic float-typed value ("double").
+ *
+ * Provides the same behavior as FloatStandard while offering a commonly used
+ * synonym name "Double".
+ *
+ * Example
+ *  - $v = Double::fromString('2.5');
+ *    $v->toString(); // "2.5"
+ *  - $v = Double::fromFloat(0.75);
+ *    (string) $v; // "0.75"
+ *
  * @psalm-immutable
  */
 readonly class Double extends FloatStandard

src/Float/Alias/FloatType.php

@@ -7,6 +7,15 @@
 use PhpTypedValues\Float\FloatStandard;
 
 /**
+ * Alias for the generic float-typed value.
+ *
+ * Provides the same behavior as FloatStandard while offering a more descriptive
+ * name for APIs that prefer "FloatType".
+ *
+ * Example
+ *  - $v = FloatType::fromString('1.25');
+ *    $v->toString(); // "1.25"
+ *
  * @psalm-immutable
  */
 readonly class FloatType extends FloatStandard

src/Float/Alias/NonNegative.php

@@ -7,9 +7,16 @@
 use PhpTypedValues\Float\FloatNonNegative;
 
 /**
- * Alias of Non-negative float (>= 0.0).
+ * Alias for non‑negative float-typed value (>= 0.0).
  *
- * Example "0.0"
+ * Provides the same behavior as FloatNonNegative while exposing a concise
+ * name suitable for APIs that prefer "NonNegative".
+ *
+ * Example
+ *  - $v = NonNegative::fromString('0.0');
+ *    $v->value(); // 0.0
+ *  - $v = NonNegative::fromFloat(10.25);
+ *    (string) $v; // "10.25"
  *
  * @psalm-immutable
  */

src/Float/Alias/Positive.php

@@ -7,6 +7,17 @@
 use PhpTypedValues\Float\FloatPositive;
 
 /**
+ * Alias for positive float-typed value (> 0.0).
+ *
+ * Provides the same behavior as FloatPositive while exposing a concise name
+ * suitable for APIs that prefer "Positive".
+ *
+ * Example
+ *  - $v = Positive::fromString('0.1');
+ *    $v->value(); // 0.1
+ *  - $v = Positive::fromFloat(2.5);
+ *    (string) $v; // "2.5"
+ *
  * @psalm-immutable
  */
 readonly class Positive extends FloatPositive

src/Float/FloatNonNegative.php

@@ -12,9 +12,16 @@
 use function sprintf;
 
 /**
- * Non-negative float (>= 0.0).
+ * Non‑negative float-typed value (>= 0.0).
  *
- * Example "0.0"
+ * Guarantees the wrapped float is zero or positive. Offers factories from
+ * validated string and native float, plus standard string formatting.
+ *
+ * Example
+ *  - $v = FloatNonNegative::fromString('0.0');
+ *    $v->value(); // 0.0
+ *  - $v = FloatNonNegative::fromFloat(10.25);
+ *    (string) $v; // "10.25"
  *
  * @psalm-immutable
  */

src/Float/FloatPositive.php

@@ -12,9 +12,16 @@
 use function sprintf;
 
 /**
- * Positive float (> 0.0).
+ * Positive float-typed value (> 0.0).
  *
- * Example "0.1"
+ * Ensures the wrapped float is strictly greater than zero. Provides factories
+ * from validated string and native float and convenient formatting helpers.
+ *
+ * Example
+ *  - $v = FloatPositive::fromString('0.1');
+ *    $v->value(); // 0.1
+ *  - $v = FloatPositive::fromFloat(2.5);
+ *    (string) $v; // "2.5"
  *
  * @psalm-immutable
  */

src/Float/FloatStandard.php

@@ -10,9 +10,16 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
- * Represents any PHP float (double).
+ * Generic float-typed value.
  *
- * Example "3.14"
+ * Wraps any PHP float (double) and provides factories from native float or
+ * validated string, along with convenient string formatting.
+ *
+ * Example
+ *  - $v = FloatStandard::fromString('3.14');
+ *    $v->value(); // 3.14 (float)
+ *  - $v = FloatStandard::fromFloat(0.5);
+ *    (string) $v; // "0.5"
  *
  * @psalm-immutable
  */