Release/v0.2.1

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [[v0.2.1](https://github.com/The-FireHub-Project/Runtime/compare/v0.2.0...v0.2.1)] – 2026-08-31
+
+### Added
+* Improved PHP docs by @dieselxxx
+
 ## [[v0.2.0](https://github.com/The-FireHub-Project/Runtime/compare/v0.1.5...v0.2.0)] – 2026-08-31
 
 ### Added

src/Math/Decimal/Arithmetic.php

@@ -40,7 +40,7 @@ trait Arithmetic {
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is not a valid decimal number.
      *
-     * @return string The sum of the two decimal values.
+     * @return numeric-string The sum of the two decimal values.
      */
     public static function add (string $left, string $right):string {
 
@@ -56,7 +56,8 @@ public static function add (string $left, string $right):string {
                 $right_fraction
             );
 
-            return $left_sign === '-' && $result !== '0'
+            /** @var numeric-string $result */
+            return $left_sign === '-' && $result !== '0' // @phpstan-ignore return.type
                 ? '-'.$result
                 : $result;
 
@@ -80,7 +81,8 @@ public static function add (string $left, string $right):string {
                 $right_fraction
             );
 
-            return $left_sign === '-' && $result !== '0'
+            /** @var numeric-string $result */
+            return $left_sign === '-' && $result !== '0' // @phpstan-ignore return.type
                 ? '-'.$result
                 : $result;
 
@@ -93,7 +95,8 @@ public static function add (string $left, string $right):string {
             $left_fraction
         );
 
-        return $right_sign === '-' && $result !== '0'
+        /** @var numeric-string $result */
+        return $right_sign === '-' && $result !== '0' // @phpstan-ignore return.type
             ? '-'.$result
             : $result;
 
@@ -116,7 +119,7 @@ public static function add (string $left, string $right):string {
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is not a valid decimal number.
      *
-     * @return string The difference between the two decimal values.
+     * @return numeric-string The difference between the two decimal values.
      */
     public static function subtract (string $left, string $right):string {
 
@@ -157,7 +160,7 @@ public static function subtract (string $left, string $right):string {
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number.
      *
-     * @return string The sum of the two positive decimal values.
+     * @return numeric-string The sum of the two positive decimal values.
      */
     private static function addPositive (string $left_integer, string $left_fraction, string $right_integer, string $right_fraction):string {
 
@@ -227,7 +230,7 @@ private static function addPositive (string $left_integer, string $left_fraction
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number.
      *
-     * @return string The difference between the two positive decimal values.
+     * @return numeric-string The difference between the two positive decimal values.
      */
     private static function subtractPositive (string $left_integer, string $left_fraction, string $right_integer, string $right_fraction):string {
 

src/Math/Decimal/Divide.php

@@ -26,6 +26,11 @@ trait Divide {
 
     /**
      * ### Divides one decimal value by another
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Runtime\Math\DecimalEngine::normalize() To normalize the decimal values.
+     * @uses \FireHub\Runtime\Math\DecimalEngine::dividePositive() To divide the positive decimal values.
+     *
      * @param non-empty-string $left <p>
      * The dividend.
      * </p>
@@ -36,15 +41,11 @@ trait Divide {
      * The number of decimal places to calculate.
      * </p>
      *
-     * @return string The quotient of the two decimal values.
-     *@throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is invalid.
+     * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is invalid.
      * @throws \FireHub\Runtime\Exception\InvalidScaleNumberException If the scale is less than zero.
      * @throws DivisionByZeroError If the divisor is zero.
      *
-     * @since 1.0.0
-     *
-     * @uses \FireHub\Runtime\Math\DecimalEngine::normalize() To normalize the decimal values.
-     * @uses \FireHub\Runtime\Math\DecimalEngine::dividePositive() To divide the positive decimal values.
+     * @return numeric-string The quotient of the two decimal values.
      *
      */
     public static function divide (string $left, string $right, int $scale = 18):string {
@@ -55,11 +56,9 @@ public static function divide (string $left, string $right, int $scale = 18):str
         if ($scale < 0)
             throw new InvalidScaleNumberException('Scale must be greater than or equal to zero.');
 
-        if ($right_integer === '0' && $right_fraction === '')
-            throw new DivisionByZeroError;
+        if ($right_integer === '0' && $right_fraction === '') throw new DivisionByZeroError;
 
-        if ($left_integer === '0' && $left_fraction === '')
-            return '0';
+        if ($left_integer === '0' && $left_fraction === '') return '0';
 
         $result = self::dividePositive(
             $left_integer,
@@ -69,7 +68,8 @@ public static function divide (string $left, string $right, int $scale = 18):str
             $scale
         );
 
-        if ($left_sign !== $right_sign && $result !== '0') return '-'.$result;
+        /** @var numeric-string $result */
+        if ($left_sign !== $right_sign && $result !== '0') return '-'.$result; // @phpstan-ignore return.type
 
         return $result;
 
@@ -105,7 +105,7 @@ public static function divide (string $left, string $right, int $scale = 18):str
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number.
      *
-     * @return string The quotient.
+     * @return numeric-string The quotient.
      */
     private static function dividePositive (string $left_integer, string $left_fraction, string $right_integer, string $right_fraction, int $scale):string {
 
@@ -162,7 +162,8 @@ private static function dividePositive (string $left_integer, string $left_fract
 
         }
 
-        $quotient = Runtime\Str\SB\Transform::trim($quotient, Side::LEFT, '0') ?: '0';
+        /** @var numeric-string $quotient */
+        $quotient = Runtime\Str\SB\Transform::trim($quotient, Side::LEFT, '0') ?: '0'; // @phpstan-ignore varTag.nativeType
 
         $fraction = '';
         for ($i = 0; $i < $scale; ++$i) {
@@ -200,7 +201,8 @@ private static function dividePositive (string $left_integer, string $left_fract
 
         if ($fraction === '') return $quotient;
 
-        return $quotient.'.'.$fraction;
+        /** @var numeric-string */
+        return $quotient.'.'.$fraction; // @phpstan-ignore varTag.nativeType
 
     }
 

src/Math/Decimal/Multiply.php

@@ -39,7 +39,7 @@ trait Multiply {
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If either decimal value is not a valid decimal number.
      *
-     * @return string The product of the two decimal values.
+     * @return numeric-string The product of the two decimal values.
      */
     public static function multiply (string $left, string $right):string {
 
@@ -57,7 +57,8 @@ public static function multiply (string $left, string $right):string {
             $right_fraction
         );
 
-        if ($left_sign !== $right_sign && $result !== '0') return '-'.$result;
+        /** @var numeric-string $result */
+        if ($left_sign !== $right_sign && $result !== '0') return '-'.$result; // @phpstan-ignore return.type
 
         return $result;
 
@@ -89,7 +90,7 @@ public static function multiply (string $left, string $right):string {
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number.
      *
-     * @return string The product of the two positive decimal values.
+     * @return numeric-string The product of the two positive decimal values.
      */
     private static function multiplyPositive (string $left_integer, string $left_fraction, string $right_integer, string $right_fraction):string {
 

src/Math/Decimal/Round.php

@@ -48,7 +48,7 @@
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number.
      * @throws \FireHub\Runtime\Exception\InvalidPrecisionException If the precision is less than zero.
      *
-     * @return string The rounded decimal value.
+     * @return numeric-string The rounded decimal value.
      */
     public static function round (string $value, int $precision = 0, RoundMode $mode = RoundMode::HALF_AWAY_FROM_ZERO):string {
 
@@ -57,7 +57,7 @@
         if ($precision < 0) throw new InvalidPrecisionException('Precision must be greater than or equal to zero.');
 
         if (Runtime\Str\SB\Inspection::length($fraction) <= $precision)
-            return $sign === '-' && ($integer !== '0' || $fraction !== '')
+            return $sign === '-' && ($integer !== '0' || $fraction !== '') // @phpstan-ignore return.type
                 ? '-'.$integer.($fraction !== '' ? '.'.$fraction : '')
                 : $integer.($fraction !== '' ? '.'.$fraction : '');
 
@@ -97,7 +97,8 @@
 
         } else $result = $integer;
 
-        return $sign === '-' && $result !== '0'
+        /** @var numeric-string $result */
+        return $sign === '-' && $result !== '0' // @phpstan-ignore return.type
             ? '-'.$result
             : $result;
 

src/Math/DecimalEngine.php

@@ -108,7 +108,7 @@ private static function comparePositive (string $left_integer, string $left_frac
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number.
      *
-     * @return array{'+'|'-', non-empty-string, string} Returns the sign, normalized integer part, and normalized
+     * @return array{'+'|'-', numeric-string, string} Returns the sign, normalized integer part, and normalized
      * fractional part.
      */
     private static function normalize (string $value):array {
@@ -136,6 +136,7 @@ private static function normalize (string $value):array {
 
         if ($integer === '0' && $fraction === '') return ['+', '0', ''];
 
+        /** @var array{'+'|'-', numeric-string, string} */
         return [$sign, $integer, $fraction];
 
     }
@@ -159,7 +160,7 @@ private static function normalize (string $value):array {
      *
      * @throws \FireHub\Runtime\Exception\InvalidDecimalNumberException If the value is not a valid decimal number.
      *
-     * @return string The normalized decimal result.
+     * @return numeric-string The normalized decimal result.
      */
     private static function normalizeResult (string $value, int $scale):string {
 
@@ -173,7 +174,8 @@ private static function normalizeResult (string $value, int $scale):string {
             .'.'
             .Runtime\Str\SB\Access::part($value, $position);
 
-        return self::normalize($value)[1]
+        /** @var numeric-string */
+        return self::normalize($value)[1] // @phpstan-ignore varTag.type
             .(self::normalize($value)[2] !== ''
                 ? '.'.self::normalize($value)[2]
                 : ''

tests/Unit/FileSystem/FolderTest.php

@@ -156,7 +156,7 @@ public function testMatch (PathSearchFlag ...$flags):void {
     #[DependsExternal(FileTest::class, 'testPutContent')]
     public function testList (?Order $order = null):void {
 
-        self::assertSame(
+        self::assertEqualsCanonicalizing(
             [
                 '.',
                 '..',