Document meaning of scale

Author: jhatlak

docs/README.md

@@ -36,7 +36,7 @@ Transformation:
 These return a new object:
 - `absolute()`: Returns the absolute (positive) value of this decimal.
 - `negate()`: Returns the negation (positive if negative and vice versa).
-- `trim()`: Remove trailing zeros after the comma (same value, but different semantic meaning in term of precision/scale).
+- `trim()`: Remove trailing zeros after the comma (same value, but different semantic meaning in terms of precision/scale).
 
 There is only one static method and acts as a convenience wrapper to create an object:
 - `create()`: Internally does `new Decimal($value)`, allows for easier chaining without need of `()` wrapping.
@@ -81,20 +81,26 @@ $decimalAdded = $decimalOne->add($decimalTwo); // Now '3.3'
 Note that due to immutability `$decimalOne` is not modified here. The re-assignment is necessary for the operation to persist.
 
 ### Precision/Scale
-Operations like `add()` use the higher of the scales of the operands.
+Operations like `add()` use the higher one of the scales of the operands.
 If both are the same, they would also stay the same.
 
-With other operations like `multiply()`, they scale would be the addition of both operands' scale:
+With other operations like `multiply()`, the scale would be the addition of both operands' scale by default:
 ```php
 $decimalOne = Decimal::create('1.55');
 $decimalTwo = Decimal::create('2.00');
 
 echo $decimalOne->multiply($decimalTwo); // Prints '3.1000'
+```
+
+To produce a result with a different number of decimal places, provide a value for the `$scale` parameter:
+```php
+$decimalOne = Decimal::create('1.55');
+$decimalTwo = Decimal::create('2.00');
 
-// Keeping 2 digit scale requires a 2nd argument
 echo $decimalOne->multiply($decimalTwo, 2); // Prints '3.10'
 ```
 
+
 ## Contributing
 
 You can contribute as pull request directly:

src/Decimal.php

@@ -56,13 +56,15 @@ class Decimal implements JsonSerializable, Stringable
     protected bool $negative = false;
 
     /**
+     * Decimal places to be applied to results
+     *
      * decimal(10,6) => 6
      */
     protected int $scale = 0;
 
     /**
      * @param object|string|float|int $value
-     * @param int|null $scale Leave empty to auto-detect.
+     * @param int|null $scale Decimal places in the result. Omit to enable auto-detection.
      */
     public function __construct(object|string|float|int $value, ?int $scale = null)
     {
@@ -143,7 +145,7 @@ protected function normalizeValue(string $value): string
      * it.
      *
      * @param object|string|float|int $value
-     * @param int|null $scale Leave empty to auto-detect.
+     * @param int|null $scale Decimal places in the result. Omit to enable auto-detection.
      *
      * @return static
      */
@@ -247,7 +249,7 @@ public function compareTo(self|string|float|int $value): int
      * Add $value to this Decimal and return the sum as a new Decimal.
      *
      * @param static|string|float|int $value
-     * @param int|null $scale Leave empty to auto-detect.
+     * @param int|null $scale Decimal places in the result. Omit to enable auto-detection.
      *
      * @return static
      */
@@ -281,7 +283,7 @@ protected function resultScale(self $a, self $b, ?int $scale = null): int
      * Decimal.
      *
      * @param static|string|float|int $value
-     * @param int|null $scale Leave empty to auto-detect.
+     * @param int|null $scale Decimal places in the result. Omit to enable auto-detection.
      *
      * @return static
      */
@@ -389,7 +391,7 @@ public function isPositive(): bool
      * Multiply this Decimal by $value and return the product as a new Decimal.
      *
      * @param static|string|float|int $value
-     * @param int|null $scale Leave empty to auto-detect.
+     * @param int|null $scale Decimal places in the result. Omit to enable auto-detection.
      *
      * @return static
      */
@@ -407,7 +409,7 @@ public function multiply(self|string|int|float $value, ?int $scale = null): stat
      * Divide this Decimal by $value and return the quotient as a new Decimal.
      *
      * @param static|string|float|int $value
-     * @param int $scale
+     * @param int $scale Decimal places in the result
      *
      * @throws \DivisionByZeroError if $value is zero.
      *
@@ -427,7 +429,7 @@ public function divide(self|string|int|float $value, int $scale): static
      * This method is equivalent to the ** operator.
      *
      * @param static|string|int $exponent
-     * @param int|null $scale Leave empty to use current.
+     * @param int|null $scale Decimal places in the result. Omit to enable auto-detection.
      *
      * @return static
      */
@@ -443,7 +445,7 @@ public function pow(self|string|int $exponent, ?int $scale = null): static
     /**
      * Returns the square root of this decimal, with the same scale as this decimal.
      *
-     * @param int|null $scale Leave empty to use current.
+     * @param int|null $scale Decimal places in the result. Omit to enable auto-detection.
      *
      * @return static
      */
@@ -460,7 +462,7 @@ public function sqrt(?int $scale = null): static
      * This method is equivalent to the % operator.
      *
      * @param static|string|int $value
-     * @param int|null $scale Leave empty to use current.
+     * @param int|null $scale Decimal places in the result. Omit to enable auto-detection.
      *
      * @return static
      */
@@ -474,7 +476,7 @@ public function mod(self|string|int $value, ?int $scale = null): static
     }
 
     /**
-     * @param int $scale
+     * @param int $scale Decimal places in the result (only used with mode "half up")
      * @param int $roundMode
      *
      * @return static
@@ -524,7 +526,7 @@ public function ceil(): static
     /**
      * The result of discarding all digits behind the defined scale.
      *
-     * @param int $scale
+     * @param int $scale Decimal places in the result
      *
      * @throws \InvalidArgumentException
      *