effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/BigDecimal.ts

@@ -1,15 +1,59 @@
 /**
- * This module provides utility functions and type class instances for working with the `BigDecimal` type in TypeScript.
- * It includes functions for basic arithmetic operations.
+ * Decimal arithmetic backed by an unscaled `bigint` and a decimal scale.
+ *
+ * `BigDecimal` is useful when values must keep their decimal representation
+ * instead of inheriting JavaScript's binary floating-point rounding, such as
+ * money, quantities, measurements, or protocol values exchanged as decimal
+ * strings. The module includes constructors, parsers, arithmetic operations,
+ * comparisons, rounding helpers, and string formatting.
+ *
+ * **Mental model**
+ *
+ * - A `BigDecimal` stores `value * 10^-scale`; `make(12345n, 2)` represents
+ *   `123.45`
+ * - Values are immutable; arithmetic returns new `BigDecimal` values
+ * - Equivalent values can have different internal scales, so equality and
+ *   ordering normalize trailing zeros
+ * - Division can produce repeating decimals, so {@link divide} and
+ *   {@link divideUnsafe} use the module's default division precision
+ *
+ * **Common tasks**
+ *
+ * - Construct values: {@link make}, {@link fromBigInt}, {@link fromString},
+ *   {@link fromNumber}
+ * - Render values: {@link format}, {@link toExponential},
+ *   {@link toNumberUnsafe}
+ * - Do arithmetic: {@link sum}, {@link subtract}, {@link multiply},
+ *   {@link divide}, {@link remainder}, {@link negate}, {@link abs}
+ * - Compare and constrain values: {@link equals}, {@link Order},
+ *   {@link isLessThan}, {@link between}, {@link clamp}, {@link min},
+ *   {@link max}
+ * - Adjust decimal places: {@link scale}, {@link round}, {@link truncate},
+ *   {@link ceil}, {@link floor}
  *
- * A `BigDecimal` allows storing any real number to arbitrary precision; which avoids common floating point errors
- * (such as 0.1 + 0.2 ≠ 0.3) at the cost of complexity.
+ * **Gotchas**
+ *
+ * - Prefer {@link fromString} or {@link fromBigInt} for external decimal data.
+ *   {@link fromNumber} can only preserve the decimal spelling of a finite
+ *   JavaScript number after any binary floating-point precision has already
+ *   been lost.
+ * - {@link divide} and {@link remainder} return `Option.none()` for division
+ *   by zero; {@link divideUnsafe} and {@link remainderUnsafe} throw instead.
+ * - Parsed scales must fit in JavaScript's safe integer range.
+ *
+ * **Example** (Decimal arithmetic)
+ *
+ * ```ts
+ * import { BigDecimal } from "effect"
  *
- * Internally, `BigDecimal` uses a `BigInt` object, paired with a 64-bit integer which determines the position of the
- * decimal point. Therefore, the precision *is not* actually arbitrary, but limited to 2<sup>63</sup> decimal places.
+ * const subtotal = BigDecimal.multiply(
+ *   BigDecimal.fromStringUnsafe("19.99"),
+ *   BigDecimal.fromBigInt(3n)
+ * )
+ * const total = BigDecimal.sum(subtotal, BigDecimal.fromStringUnsafe("1.50"))
  *
- * It is not recommended to convert a floating point number to a decimal directly, as the floating point representation
- * may be unexpected.
+ * console.log(BigDecimal.format(total)) // "61.47"
+ * ```
  *
  * @since 2.0.0
  */
@@ -33,6 +77,11 @@ const TypeId = "~effect/BigDecimal"
 /**
  * Represents an arbitrary precision decimal number.
  *
+ * **When to use**
+ *
+ * Use when decimal arithmetic needs to avoid JavaScript floating point
+ * representation errors.
+ *
  * **Example** (Inspecting BigDecimal storage)
  *
  * ```ts
@@ -83,7 +132,11 @@ const BigDecimalProto: Omit<BigDecimal, "value" | "scale" | "normalized"> = {
 } as const
 
 /**
- * Checks if a given value is a `BigDecimal`.
+ * Checks whether a given value is a `BigDecimal`.
+ *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `BigDecimal`.
  *
  * **Example** (Checking BigDecimal values)
  *
@@ -104,6 +157,11 @@ export const isBigDecimal = (u: unknown): u is BigDecimal => hasProperty(u, Type
 /**
  * Creates a `BigDecimal` from a `bigint` value and a scale.
  *
+ * **When to use**
+ *
+ * Use to construct a decimal directly from its unscaled integer value and
+ * decimal scale.
+ *
  * **Example** (Creating decimals from bigint and scale)
  *
  * ```ts
@@ -118,6 +176,8 @@ export const isBigDecimal = (u: unknown): u is BigDecimal => hasProperty(u, Type
  * console.log(BigDecimal.format(integer)) // "42"
  * ```
  *
+ * @see {@link fromBigInt} for constructing an integer decimal from a `bigint`
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -156,6 +216,11 @@ const one = makeNormalizedUnsafe(bigint1, 0)
 /**
  * Normalizes a given `BigDecimal` by removing trailing zeros.
  *
+ * **When to use**
+ *
+ * Use to canonicalize decimals that have equivalent values but different
+ * internal scales.
+ *
  * **Example** (Normalizing trailing zeros)
  *
  * ```ts
@@ -172,6 +237,8 @@ const one = makeNormalizedUnsafe(bigint1, 0)
  * )
  * ```
  *
+ * @see {@link format} for rendering normalized decimals as strings
+ *
  * @category scaling
  * @since 2.0.0
  */
@@ -205,7 +272,11 @@ export const normalize = (self: BigDecimal): BigDecimal => {
 }
 
 /**
- * Scales a `BigDecimal` to the specified scale.
+ * Changes a `BigDecimal` to the specified scale.
+ *
+ * **When to use**
+ *
+ * Use to change how many decimal places are represented by a `BigDecimal`.
  *
  * **Details**
  *
@@ -229,12 +300,18 @@ export const normalize = (self: BigDecimal): BigDecimal => {
  * console.log(BigDecimal.format(reduced)) // "123.4"
  * ```
  *
+ * @see {@link round} for changing scale with configurable rounding
+ *
  * @category scaling
  * @since 2.0.0
  */
 export const scale: {
   /**
-   * Scales a `BigDecimal` to the specified scale.
+   * Changes a `BigDecimal` to the specified scale.
+   *
+   * **When to use**
+   *
+   * Use to change how many decimal places are represented by a `BigDecimal`.
    *
    * **Details**
    *
@@ -258,12 +335,18 @@ export const scale: {
    * console.log(BigDecimal.format(reduced)) // "123.4"
    * ```
    *
+   * @see {@link round} for changing scale with configurable rounding
+   *
    * @category scaling
    * @since 2.0.0
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Scales a `BigDecimal` to the specified scale.
+   * Changes a `BigDecimal` to the specified scale.
+   *
+   * **When to use**
+   *
+   * Use to change how many decimal places are represented by a `BigDecimal`.
    *
    * **Details**
    *
@@ -287,6 +370,8 @@ export const scale: {
    * console.log(BigDecimal.format(reduced)) // "123.4"
    * ```
    *
+   * @see {@link round} for changing scale with configurable rounding
+   *
    * @category scaling
    * @since 2.0.0
    */
@@ -306,6 +391,10 @@ export const scale: {
 /**
  * Provides an addition operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to add two `BigDecimal` values.
+ *
  * **Example** (Adding decimals)
  *
  * ```ts
@@ -318,6 +407,8 @@ export const scale: {
  * )
  * ```
  *
+ * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -325,6 +416,10 @@ export const sum: {
   /**
    * Provides an addition operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to add two `BigDecimal` values.
+   *
    * **Example** (Adding decimals)
    *
    * ```ts
@@ -337,6 +432,8 @@ export const sum: {
    * )
    * ```
    *
+   * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -344,6 +441,10 @@ export const sum: {
   /**
    * Provides an addition operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to add two `BigDecimal` values.
+   *
    * **Example** (Adding decimals)
    *
    * ```ts
@@ -356,6 +457,8 @@ export const sum: {
    * )
    * ```
    *
+   * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -383,6 +486,10 @@ export const sum: {
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their sum as a single `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to sum all `BigDecimal` values in an iterable.
+ *
  * **Example** (Adding multiple decimals)
  *
  * ```ts
@@ -395,6 +502,8 @@ export const sum: {
  * )
  * ```
  *
+ * @see {@link sum} for adding two `BigDecimal` values
+ *
  * @category math
  * @since 3.16.0
  */
@@ -409,6 +518,10 @@ export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
 /**
  * Provides a multiplication operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to multiply two `BigDecimal` values.
+ *
  * **Example** (Multiplying decimals)
  *
  * ```ts
@@ -421,6 +534,8 @@ export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
  * )
  * ```
  *
+ * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -428,6 +543,10 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to multiply two `BigDecimal` values.
+   *
    * **Example** (Multiplying decimals)
    *
    * ```ts
@@ -440,6 +559,8 @@ export const multiply: {
    * )
    * ```
    *
+   * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -447,6 +568,10 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to multiply two `BigDecimal` values.
+   *
    * **Example** (Multiplying decimals)
    *
    * ```ts
@@ -459,6 +584,8 @@ export const multiply: {
    * )
    * ```
    *
+   * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -474,6 +601,10 @@ export const multiply: {
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their multiplication as a single `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to multiply all `BigDecimal` values in an iterable.
+ *
  * **Example** (Multiplying multiple decimals)
  *
  * ```ts
@@ -486,6 +617,8 @@ export const multiply: {
  * )
  * ```
  *
+ * @see {@link multiply} for multiplying two `BigDecimal` values
+ *
  * @category math
  * @since 4.0.0
  */
@@ -503,6 +636,10 @@ export const multiplyAll = (collection: Iterable<BigDecimal>): BigDecimal => {
 /**
  * Provides a subtraction operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to subtract one `BigDecimal` value from another.
+ *
  * **Example** (Subtracting decimals)
  *
  * ```ts
@@ -522,6 +659,10 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to subtract one `BigDecimal` value from another.
+   *
    * **Example** (Subtracting decimals)
    *
    * ```ts
@@ -541,6 +682,10 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to subtract one `BigDecimal` value from another.
+   *
    * **Example** (Subtracting decimals)
    *
    * ```ts
@@ -646,7 +791,12 @@ export const roundTerminal = (n: bigint): bigint => {
 }
 
 /**
- * Provides a division operation on `BigDecimal`s.
+ * Divides `BigDecimal`s safely.
+ *
+ * **When to use**
+ *
+ * Use to divide `BigDecimal` values while representing division by zero as
+ * `Option.none`.
  *
  * **Details**
  *
@@ -685,12 +835,20 @@ export const roundTerminal = (n: bigint): bigint => {
  * ) // true
  * ```
  *
+ * @see {@link divideUnsafe} for division that throws when the divisor is zero
+ * @see {@link remainder} for the decimal remainder operation
+ *
  * @category math
  * @since 2.0.0
  */
 export const divide: {
   /**
-   * Provides a division operation on `BigDecimal`s.
+   * Divides `BigDecimal`s safely.
+   *
+   * **When to use**
+   *
+   * Use to divide `BigDecimal` values while representing division by zero as
+   * `Option.none`.
    *
    * **Details**
    *
@@ -729,12 +887,20 @@ export const divide: {
    * ) // true
    * ```
    *
+   * @see {@link divideUnsafe} for division that throws when the divisor is zero
+   * @see {@link remainder} for the decimal remainder operation
+   *
    * @category math
    * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
   /**
-   * Provides a division operation on `BigDecimal`s.
+   * Divides `BigDecimal`s safely.
+   *
+   * **When to use**
+   *
+   * Use to divide `BigDecimal` values while representing division by zero as
+   * `Option.none`.
    *
    * **Details**
    *
@@ -773,6 +939,9 @@ export const divide: {
    * ) // true
    * ```
    *
+   * @see {@link divideUnsafe} for division that throws when the divisor is zero
+   * @see {@link remainder} for the decimal remainder operation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -797,6 +966,11 @@ export const divide: {
 /**
  * Provides an unsafe division operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use when you need the decimal quotient and the divisor is known to be
+ * non-zero, so division by zero should be a thrown exception.
+ *
  * **Details**
  *
  * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -815,6 +989,8 @@ export const divide: {
  * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
  * ```
  *
+ * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
@@ -822,6 +998,11 @@ export const divideUnsafe: {
   /**
    * Provides an unsafe division operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use when you need the decimal quotient and the divisor is known to be
+   * non-zero, so division by zero should be a thrown exception.
+   *
    * **Details**
    *
    * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -840,6 +1021,8 @@ export const divideUnsafe: {
    * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
    * ```
    *
+   * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -847,6 +1030,11 @@ export const divideUnsafe: {
   /**
    * Provides an unsafe division operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use when you need the decimal quotient and the divisor is known to be
+   * non-zero, so division by zero should be a thrown exception.
+   *
    * **Details**
    *
    * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -865,6 +1053,8 @@ export const divideUnsafe: {
    * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
    * ```
    *
+   * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -888,6 +1078,11 @@ export const divideUnsafe: {
 /**
  * Provides an `Order` instance for `BigDecimal` that allows comparing and sorting BigDecimal values.
  *
+ * **When to use**
+ *
+ * Use when sorting or comparing decimal values through APIs that accept an
+ * ordering instance.
+ *
  * **Example** (Comparing decimals)
  *
  * ```ts
@@ -925,6 +1120,10 @@ export const Order: order.Order<BigDecimal> = order.make((self, that) => {
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is strictly less than another.
+ *
  * **Example** (Checking less-than comparisons)
  *
  * ```ts
@@ -952,6 +1151,10 @@ export const isLessThan: {
   /**
    * Returns `true` if the first argument is less than the second, otherwise `false`.
    *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is strictly less than another.
+   *
    * **Example** (Checking less-than comparisons)
    *
    * ```ts
@@ -979,6 +1182,10 @@ export const isLessThan: {
   /**
    * Returns `true` if the first argument is less than the second, otherwise `false`.
    *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is strictly less than another.
+   *
    * **Example** (Checking less-than comparisons)
    *
    * ```ts
@@ -1006,7 +1213,11 @@ export const isLessThan: {
 } = order.isLessThan(Order)
 
 /**
- * Checks if a given `BigDecimal` is less than or equal to the provided one.
+ * Checks whether a given `BigDecimal` is less than or equal to the provided one.
+ *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is less than or equal to another.
  *
  * **Example** (Checking less-than-or-equal comparisons)
  *
@@ -1033,7 +1244,11 @@ export const isLessThan: {
  */
 export const isLessThanOrEqualTo: {
   /**
-   * Checks if a given `BigDecimal` is less than or equal to the provided one.
+   * Checks whether a given `BigDecimal` is less than or equal to the provided one.
+   *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is less than or equal to another.
    *
    * **Example** (Checking less-than-or-equal comparisons)
    *
@@ -1060,7 +1275,11 @@ export const isLessThanOrEqualTo: {
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
-   * Checks if a given `BigDecimal` is less than or equal to the provided one.
+   * Checks whether a given `BigDecimal` is less than or equal to the provided one.
+   *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is less than or equal to another.
    *
    * **Example** (Checking less-than-or-equal comparisons)
    *
@@ -1091,6 +1310,10 @@ export const isLessThanOrEqualTo: {
 /**
  * Returns `true` if the first argument is greater than the second, otherwise `false`.
  *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is strictly greater than another.
+ *
  * **Example** (Checking greater-than comparisons)
  *
  * ```ts
@@ -1118,6 +1341,10 @@ export const isGreaterThan: {
   /**
    * Returns `true` if the first argument is greater than the second, otherwise `false`.
    *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is strictly greater than another.
+   *
    * **Example** (Checking greater-than comparisons)
    *
    * ```ts
@@ -1145,6 +1372,10 @@ export const isGreaterThan: {
   /**
    * Returns `true` if the first argument is greater than the second, otherwise `false`.
    *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is strictly greater than another.
+   *
    * **Example** (Checking greater-than comparisons)
    *
    * ```ts
@@ -1172,7 +1403,11 @@ export const isGreaterThan: {
 } = order.isGreaterThan(Order)
 
 /**
- * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+ * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
+ *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is greater than or equal to another.
  *
  * **Example** (Checking greater-than-or-equal comparisons)
  *
@@ -1199,7 +1434,11 @@ export const isGreaterThan: {
  */
 export const isGreaterThanOrEqualTo: {
   /**
-   * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+   * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
+   *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is greater than or equal to another.
    *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
@@ -1226,7 +1465,11 @@ export const isGreaterThanOrEqualTo: {
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
-   * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+   * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
+   *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is greater than or equal to another.
    *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
@@ -1255,7 +1498,11 @@ export const isGreaterThanOrEqualTo: {
 } = order.isGreaterThanOrEqualTo(Order)
 
 /**
- * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+ * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` falls inside an inclusive range.
  *
  * **Example** (Checking decimal ranges)
  *
@@ -1273,12 +1520,18 @@ export const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
  * ```
  *
+ * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+ *
  * @category predicates
  * @since 2.0.0
  */
 export const between: {
   /**
-   * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+   * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+   *
+   * **When to use**
+   *
+   * Use to test whether a `BigDecimal` falls inside an inclusive range.
    *
    * **Example** (Checking decimal ranges)
    *
@@ -1296,6 +1549,8 @@ export const between: {
    * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
    * ```
    *
+   * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1306,7 +1561,11 @@ export const between: {
     }
   ): (self: BigDecimal) => boolean
   /**
-   * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+   * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+   *
+   * **When to use**
+   *
+   * Use to test whether a `BigDecimal` falls inside an inclusive range.
    *
    * **Example** (Checking decimal ranges)
    *
@@ -1324,6 +1583,8 @@ export const between: {
    * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
    * ```
    *
+   * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1339,6 +1600,10 @@ export const between: {
 /**
  * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
  *
+ * **When to use**
+ *
+ * Use to force a `BigDecimal` into an inclusive range.
+ *
  * **Details**
  *
  * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1370,6 +1635,8 @@ export const between: {
  * )
  * ```
  *
+ * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1377,6 +1644,10 @@ export const clamp: {
   /**
    * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **When to use**
+   *
+   * Use to force a `BigDecimal` into an inclusive range.
+   *
    * **Details**
    *
    * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1408,6 +1679,8 @@ export const clamp: {
    * )
    * ```
    *
+   * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1420,6 +1693,10 @@ export const clamp: {
   /**
    * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **When to use**
+   *
+   * Use to force a `BigDecimal` into an inclusive range.
+   *
    * **Details**
    *
    * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1451,6 +1728,8 @@ export const clamp: {
    * )
    * ```
    *
+   * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1466,6 +1745,10 @@ export const clamp: {
 /**
  * Returns the minimum between two `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to select the smaller of two `BigDecimal` values.
+ *
  * **Example** (Selecting the smaller decimal)
  *
  * ```ts
@@ -1478,6 +1761,8 @@ export const clamp: {
  * )
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1485,6 +1770,10 @@ export const min: {
   /**
    * Returns the minimum between two `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to select the smaller of two `BigDecimal` values.
+   *
    * **Example** (Selecting the smaller decimal)
    *
    * ```ts
@@ -1497,6 +1786,8 @@ export const min: {
    * )
    * ```
    *
+   * @see {@link max} for selecting the larger value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1504,6 +1795,10 @@ export const min: {
   /**
    * Returns the minimum between two `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to select the smaller of two `BigDecimal` values.
+   *
    * **Example** (Selecting the smaller decimal)
    *
    * ```ts
@@ -1516,6 +1811,8 @@ export const min: {
    * )
    * ```
    *
+   * @see {@link max} for selecting the larger value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1525,6 +1822,10 @@ export const min: {
 /**
  * Returns the maximum between two `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to select the larger of two `BigDecimal` values.
+ *
  * **Example** (Selecting the larger decimal)
  *
  * ```ts
@@ -1537,6 +1838,8 @@ export const min: {
  * )
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1544,6 +1847,10 @@ export const max: {
   /**
    * Returns the maximum between two `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to select the larger of two `BigDecimal` values.
+   *
    * **Example** (Selecting the larger decimal)
    *
    * ```ts
@@ -1556,6 +1863,8 @@ export const max: {
    * )
    * ```
    *
+   * @see {@link min} for selecting the smaller value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1563,6 +1872,10 @@ export const max: {
   /**
    * Returns the maximum between two `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to select the larger of two `BigDecimal` values.
+   *
    * **Example** (Selecting the larger decimal)
    *
    * ```ts
@@ -1575,6 +1888,8 @@ export const max: {
    * )
    * ```
    *
+   * @see {@link min} for selecting the smaller value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1584,6 +1899,10 @@ export const max: {
 /**
  * Determines the sign of a given `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to classify a `BigDecimal` as negative, zero, or positive.
+ *
  * **Example** (Reading decimal signs)
  *
  * ```ts
@@ -1603,6 +1922,10 @@ export const sign = (n: BigDecimal): Ordering => n.value === bigint0 ? 0 : n.val
 /**
  * Determines the absolute value of a given `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to remove the sign from a `BigDecimal` while preserving its magnitude.
+ *
  * **Example** (Calculating absolute values)
  *
  * ```ts
@@ -1622,6 +1945,10 @@ export const abs = (n: BigDecimal): BigDecimal => n.value < bigint0 ? make(-n.va
 /**
  * Provides a negate operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to flip the sign of a `BigDecimal`.
+ *
  * **Example** (Negating decimals)
  *
  * ```ts
@@ -1638,7 +1965,13 @@ export const abs = (n: BigDecimal): BigDecimal => n.value < bigint0 ? make(-n.va
 export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
 
 /**
- * Returns the remainder left over when one operand is divided by a second operand.
+ * Computes the decimal remainder safely when one operand is divided by a second
+ * operand.
+ *
+ * **When to use**
+ *
+ * Use to compute a decimal remainder while representing division by zero as
+ * `Option.none`.
  *
  * **Details**
  *
@@ -1673,12 +2006,21 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
  * )
  * ```
  *
+ * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+ * @see {@link divide} for decimal quotient calculation
+ *
  * @category math
  * @since 2.0.0
  */
 export const remainder: {
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
+   * Computes the decimal remainder safely when one operand is divided by a second
+   * operand.
+   *
+   * **When to use**
+   *
+   * Use to compute a decimal remainder while representing division by zero as
+   * `Option.none`.
    *
    * **Details**
    *
@@ -1713,12 +2055,21 @@ export const remainder: {
    * )
    * ```
    *
+   * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+   * @see {@link divide} for decimal quotient calculation
+   *
    * @category math
    * @since 2.0.0
    */
   (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
+   * Computes the decimal remainder safely when one operand is divided by a second
+   * operand.
+   *
+   * **When to use**
+   *
+   * Use to compute a decimal remainder while representing division by zero as
+   * `Option.none`.
    *
    * **Details**
    *
@@ -1753,6 +2104,9 @@ export const remainder: {
    * )
    * ```
    *
+   * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+   * @see {@link divide} for decimal quotient calculation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1767,7 +2121,13 @@ export const remainder: {
 })
 
 /**
- * Returns the remainder left over when one operand is divided by a second operand.
+ * Returns the decimal remainder left over when one operand is divided by a
+ * non-zero second operand, throwing for division by zero.
+ *
+ * **When to use**
+ *
+ * Use when you need the decimal remainder and the divisor is known to be
+ * non-zero, so division by zero should be a thrown exception.
  *
  * **Gotchas**
  *
@@ -1793,12 +2153,20 @@ export const remainder: {
  * )
  * ```
  *
+ * @see {@link remainder} for returning `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
 export const remainderUnsafe: {
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
+   * Returns the decimal remainder left over when one operand is divided by a
+   * non-zero second operand, throwing for division by zero.
+   *
+   * **When to use**
+   *
+   * Use when you need the decimal remainder and the divisor is known to be
+   * non-zero, so division by zero should be a thrown exception.
    *
    * **Gotchas**
    *
@@ -1824,12 +2192,20 @@ export const remainderUnsafe: {
    * )
    * ```
    *
+   * @see {@link remainder} for returning `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
   (divisor: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
+   * Returns the decimal remainder left over when one operand is divided by a
+   * non-zero second operand, throwing for division by zero.
+   *
+   * **When to use**
+   *
+   * Use when you need the decimal remainder and the divisor is known to be
+   * non-zero, so division by zero should be a thrown exception.
    *
    * **Gotchas**
    *
@@ -1855,6 +2231,8 @@ export const remainderUnsafe: {
    * )
    * ```
    *
+   * @see {@link remainder} for returning `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -1871,6 +2249,11 @@ export const remainderUnsafe: {
 /**
  * Provides an `Equivalence` instance for `BigDecimal` that determines equality between BigDecimal values.
  *
+ * **When to use**
+ *
+ * Use when comparing decimal values through APIs that accept an equivalence
+ * relation.
+ *
  * **Example** (Checking decimal equivalence)
  *
  * ```ts
@@ -1900,7 +2283,11 @@ export const Equivalence: Equ.Equivalence<BigDecimal> = Equ.make((self, that) =>
 })
 
 /**
- * Checks if two `BigDecimal`s are equal.
+ * Checks whether two `BigDecimal`s are equal.
+ *
+ * **When to use**
+ *
+ * Use to compare two `BigDecimal` values for numeric equality.
  *
  * **Example** (Checking decimal equality)
  *
@@ -1915,12 +2302,18 @@ export const Equivalence: Equ.Equivalence<BigDecimal> = Equ.make((self, that) =>
  * console.log(BigDecimal.equals(a, c)) // false
  * ```
  *
+ * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+ *
  * @category predicates
  * @since 2.0.0
  */
 export const equals: {
   /**
-   * Checks if two `BigDecimal`s are equal.
+   * Checks whether two `BigDecimal`s are equal.
+   *
+   * **When to use**
+   *
+   * Use to compare two `BigDecimal` values for numeric equality.
    *
    * **Example** (Checking decimal equality)
    *
@@ -1935,12 +2328,18 @@ export const equals: {
    * console.log(BigDecimal.equals(a, c)) // false
    * ```
    *
+   * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+   *
    * @category predicates
    * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
-   * Checks if two `BigDecimal`s are equal.
+   * Checks whether two `BigDecimal`s are equal.
+   *
+   * **When to use**
+   *
+   * Use to compare two `BigDecimal` values for numeric equality.
    *
    * **Example** (Checking decimal equality)
    *
@@ -1955,6 +2354,8 @@ export const equals: {
    * console.log(BigDecimal.equals(a, c)) // false
    * ```
    *
+   * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1964,6 +2365,10 @@ export const equals: {
 /**
  * Creates a `BigDecimal` from a `bigint` value.
  *
+ * **When to use**
+ *
+ * Use to construct an integer `BigDecimal` from a `bigint`.
+ *
  * **Example** (Creating decimals from bigint)
  *
  * ```ts
@@ -1976,13 +2381,20 @@ export const equals: {
  * console.log(BigDecimal.format(largeBigInt)) // "9007199254740991"
  * ```
  *
+ * @see {@link make} for constructing a decimal with an explicit scale
+ *
  * @category constructors
  * @since 2.0.0
  */
 export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
 
 /**
- * Creates a `BigDecimal` from a `number` value.
+ * Creates a `BigDecimal` from a finite `number`, throwing for non-finite input.
+ *
+ * **When to use**
+ *
+ * Use when a finite JavaScript number must become a `BigDecimal` and invalid
+ * input should throw.
  *
  * **Gotchas**
  *
@@ -2000,6 +2412,8 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
  * assert.deepStrictEqual(BigDecimal.fromNumberUnsafe(123.456), BigDecimal.make(123456n, 3))
  * ```
  *
+ * @see {@link fromNumber} for returning `Option.none` when the number is not finite
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -2008,7 +2422,12 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
 }
 
 /**
- * Creates a `BigDecimal` from a `number` value.
+ * Creates a `BigDecimal` safely from a finite `number`.
+ *
+ * **When to use**
+ *
+ * Use to convert a finite JavaScript number to a `BigDecimal` without throwing
+ * on invalid input.
  *
  * **Details**
  *
@@ -2033,6 +2452,9 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
  * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), Option.none())
  * ```
  *
+ * @see {@link fromNumberUnsafe} for throwing when the number is not finite
+ * @see {@link fromString} for parsing decimal strings directly
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -2051,7 +2473,11 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
 }
 
 /**
- * Safely parses a decimal string into a `BigDecimal`.
+ * Parses a decimal string into a `BigDecimal` safely.
+ *
+ * **When to use**
+ *
+ * Use to parse external decimal text without throwing on invalid input.
  *
  * **Details**
  *
@@ -2073,6 +2499,9 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
  * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
  * ```
  *
+ * @see {@link fromStringUnsafe} for parsing that throws on invalid input
+ * @see {@link fromNumber} for converting finite JavaScript numbers
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -2125,6 +2554,10 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  * Parses a decimal string into a `BigDecimal`, throwing if the string is
  * invalid.
  *
+ * **When to use**
+ *
+ * Use when decimal text is expected to be valid and parse errors should throw.
+ *
  * **Details**
  *
  * Accepts the same syntax as `fromString`. Use `fromString` when invalid input
@@ -2141,6 +2574,8 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  * assert.throws(() => BigDecimal.fromStringUnsafe("123.abc"))
  * ```
  *
+ * @see {@link fromString} for returning `Option.none` on invalid input
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -2151,6 +2586,10 @@ export const fromStringUnsafe = (s: string): BigDecimal => {
 /**
  * Formats a `BigDecimal` as a string.
  *
+ * **When to use**
+ *
+ * Use to render a `BigDecimal` as plain decimal text when possible.
+ *
  * **Details**
  *
  * The value is normalized before formatting. Scientific notation is used when
@@ -2168,6 +2607,8 @@ export const fromStringUnsafe = (s: string): BigDecimal => {
  * assert.deepStrictEqual(BigDecimal.format(BigDecimal.fromStringUnsafe("-0.00000123")), "-0.00000123")
  * ```
  *
+ * @see {@link toExponential} for always rendering scientific notation
+ *
  * @category converting
  * @since 2.0.0
  */
@@ -2205,6 +2646,10 @@ export const format = (n: BigDecimal): string => {
 /**
  * Formats a given `BigDecimal` as a `string` in scientific notation.
  *
+ * **When to use**
+ *
+ * Use to render a `BigDecimal` in scientific notation.
+ *
  * **Example** (Formatting decimals exponentially)
  *
  * ```ts
@@ -2214,6 +2659,8 @@ export const format = (n: BigDecimal): string => {
  * assert.deepStrictEqual(BigDecimal.toExponential(BigDecimal.make(123456n, -5)), "1.23456e+10")
  * ```
  *
+ * @see {@link format} for plain decimal formatting when possible
+ *
  * @category converting
  * @since 3.11.0
  */
@@ -2239,6 +2686,11 @@ export const toExponential = (n: BigDecimal): string => {
 /**
  * Converts a `BigDecimal` to a JavaScript `number`.
  *
+ * **When to use**
+ *
+ * Use when an interop boundary requires a JavaScript number and can tolerate
+ * precision loss.
+ *
  * **Gotchas**
  *
  * This conversion is unsafe because the result can lose integer or fractional
@@ -2254,13 +2706,19 @@ export const toExponential = (n: BigDecimal): string => {
  * assert.deepStrictEqual(BigDecimal.toNumberUnsafe(BigDecimal.fromStringUnsafe("123.456")), 123.456)
  * ```
  *
+ * @see {@link format} for preserving decimal precision as text
+ *
  * @category converting
  * @since 4.0.0
  */
 export const toNumberUnsafe = (n: BigDecimal): number => Number(format(n))
 
 /**
- * Checks if a given `BigDecimal` is an integer.
+ * Checks whether a given `BigDecimal` is an integer.
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` has no fractional decimal part.
  *
  * **Example** (Checking integer decimals)
  *
@@ -2279,7 +2737,11 @@ export const toNumberUnsafe = (n: BigDecimal): number => Number(format(n))
 export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
 
 /**
- * Checks if a given `BigDecimal` is `0`.
+ * Checks whether a given `BigDecimal` is `0`.
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is exactly zero.
  *
  * **Example** (Checking zero decimals)
  *
@@ -2297,7 +2759,11 @@ export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
 export const isZero = (n: BigDecimal): boolean => n.value === bigint0
 
 /**
- * Checks if a given `BigDecimal` is negative.
+ * Checks whether a given `BigDecimal` is negative.
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is less than zero.
  *
  * **Example** (Checking negative decimals)
  *
@@ -2316,7 +2782,11 @@ export const isZero = (n: BigDecimal): boolean => n.value === bigint0
 export const isNegative = (n: BigDecimal): boolean => n.value < bigint0
 
 /**
- * Checks if a given `BigDecimal` is positive.
+ * Checks whether a given `BigDecimal` is positive.
+ *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is greater than zero.
  *
  * **Example** (Checking positive decimals)
  *
@@ -2339,6 +2809,11 @@ const isBigDecimalArgs = (args: IArguments) => isBigDecimal(args[0])
 /**
  * Rounding modes for `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use with `round` to choose how discarded digits affect a `BigDecimal`
+ * rounded to a target scale.
+ *
  * **Details**
  *
  * - `ceil`: round towards positive infinity
@@ -2352,6 +2827,11 @@ const isBigDecimalArgs = (args: IArguments) => isBigDecimal(args[0])
  * - `half-even`: round to the nearest neighbor; if equidistant round to the neighbor with an even digit
  * - `half-odd`: round to the nearest neighbor; if equidistant round to the neighbor with an odd digit
  *
+ * @see {@link round} for configurable rounding with a `RoundingMode`
+ * @see {@link ceil} for fixed rounding toward positive infinity
+ * @see {@link floor} for fixed rounding toward negative infinity
+ * @see {@link truncate} for fixed rounding toward zero
+ *
  * @category math
  * @since 3.16.0
  */
@@ -2368,7 +2848,11 @@ export type RoundingMode =
   | "half-odd"
 
 /**
- * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+ * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
+ *
+ * **When to use**
+ *
+ * Use to round a decimal at a requested scale with an explicit rounding mode.
  *
  * **Example** (Rounding decimals)
  *
@@ -2386,12 +2870,20 @@ export type RoundingMode =
  * )
  * ```
  *
+ * @see {@link ceil} for fixed rounding toward positive infinity
+ * @see {@link floor} for fixed rounding toward negative infinity
+ * @see {@link truncate} for fixed rounding toward zero
+ *
  * @category math
  * @since 3.16.0
  */
 export const round: {
   /**
-   * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+   * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
+   *
+   * **When to use**
+   *
+   * Use to round a decimal at a requested scale with an explicit rounding mode.
    *
    * **Example** (Rounding decimals)
    *
@@ -2409,12 +2901,20 @@ export const round: {
    * )
    * ```
    *
+   * @see {@link ceil} for fixed rounding toward positive infinity
+   * @see {@link floor} for fixed rounding toward negative infinity
+   * @see {@link truncate} for fixed rounding toward zero
+   *
    * @category math
    * @since 3.16.0
    */
   (options: { scale?: number; mode?: RoundingMode }): (self: BigDecimal) => BigDecimal
   /**
-   * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+   * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
+   *
+   * **When to use**
+   *
+   * Use to round a decimal at a requested scale with an explicit rounding mode.
    *
    * **Example** (Rounding decimals)
    *
@@ -2432,6 +2932,10 @@ export const round: {
    * )
    * ```
    *
+   * @see {@link ceil} for fixed rounding toward positive infinity
+   * @see {@link floor} for fixed rounding toward negative infinity
+   * @see {@link truncate} for fixed rounding toward zero
+   *
    * @category math
    * @since 3.16.0
    */
@@ -2484,9 +2988,13 @@ export const round: {
 })
 
 /**
- * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+ * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
  * rounding toward zero.
  *
+ * **When to use**
+ *
+ * Use to remove digits beyond a requested scale by rounding toward zero.
+ *
  * **Example** (Truncating decimals)
  *
  * ```ts
@@ -2496,14 +3004,22 @@ export const round: {
  * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
  * ```
  *
+ * @see {@link round} for configurable rounding modes
+ * @see {@link ceil} for rounding toward positive infinity
+ * @see {@link floor} for rounding toward negative infinity
+ *
  * @category math
  * @since 3.16.0
  */
 export const truncate: {
   /**
-   * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+   * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
    * rounding toward zero.
    *
+   * **When to use**
+   *
+   * Use to remove digits beyond a requested scale by rounding toward zero.
+   *
    * **Example** (Truncating decimals)
    *
    * ```ts
@@ -2513,14 +3029,22 @@ export const truncate: {
    * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
    * ```
    *
+   * @see {@link round} for configurable rounding modes
+   * @see {@link ceil} for rounding toward positive infinity
+   * @see {@link floor} for rounding toward negative infinity
+   *
    * @category math
    * @since 3.16.0
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+   * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
    * rounding toward zero.
    *
+   * **When to use**
+   *
+   * Use to remove digits beyond a requested scale by rounding toward zero.
+   *
    * **Example** (Truncating decimals)
    *
    * ```ts
@@ -2530,6 +3054,10 @@ export const truncate: {
    * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
    * ```
    *
+   * @see {@link round} for configurable rounding modes
+   * @see {@link ceil} for rounding toward positive infinity
+   * @see {@link floor} for rounding toward negative infinity
+   *
    * @category math
    * @since 3.16.0
    */
@@ -2544,7 +3072,21 @@ export const truncate: {
 })
 
 /**
- * Calculate the ceiling of a `BigDecimal` at the given scale.
+ * Computes the ceiling of a `BigDecimal` at the given scale.
+ *
+ * **When to use**
+ *
+ * Use to round a decimal toward positive infinity at a requested scale.
+ *
+ * **Details**
+ *
+ * The default scale is `0`. Positive scales keep digits to the right of the
+ * decimal point, and negative scales round positions to the left of the decimal
+ * point.
+ *
+ * @see {@link floor} for rounding toward negative infinity
+ * @see {@link truncate} for rounding toward zero
+ * @see {@link round} for configurable rounding modes
  *
  * **Example** (Rounding decimals up)
  *
@@ -2564,7 +3106,21 @@ export const truncate: {
  */
 export const ceil: {
   /**
-   * Calculate the ceiling of a `BigDecimal` at the given scale.
+   * Computes the ceiling of a `BigDecimal` at the given scale.
+   *
+   * **When to use**
+   *
+   * Use to round a decimal toward positive infinity at a requested scale.
+   *
+   * **Details**
+   *
+   * The default scale is `0`. Positive scales keep digits to the right of the
+   * decimal point, and negative scales round positions to the left of the decimal
+   * point.
+   *
+   * @see {@link floor} for rounding toward negative infinity
+   * @see {@link truncate} for rounding toward zero
+   * @see {@link round} for configurable rounding modes
    *
    * **Example** (Rounding decimals up)
    *
@@ -2584,7 +3140,21 @@ export const ceil: {
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Calculate the ceiling of a `BigDecimal` at the given scale.
+   * Computes the ceiling of a `BigDecimal` at the given scale.
+   *
+   * **When to use**
+   *
+   * Use to round a decimal toward positive infinity at a requested scale.
+   *
+   * **Details**
+   *
+   * The default scale is `0`. Positive scales keep digits to the right of the
+   * decimal point, and negative scales round positions to the left of the decimal
+   * point.
+   *
+   * @see {@link floor} for rounding toward negative infinity
+   * @see {@link truncate} for rounding toward zero
+   * @see {@link round} for configurable rounding modes
    *
    * **Example** (Rounding decimals up)
    *
@@ -2647,7 +3217,11 @@ export const digitAt: {
 })
 
 /**
- * Calculate the floor of a `BigDecimal` at the given scale.
+ * Computes the floor of a `BigDecimal` at the given scale.
+ *
+ * **When to use**
+ *
+ * Use to round a decimal toward negative infinity at a requested scale.
  *
  * **Example** (Rounding decimals down)
  *
@@ -2665,12 +3239,20 @@ export const digitAt: {
  * )
  * ```
  *
+ * @see {@link ceil} for rounding toward positive infinity
+ * @see {@link truncate} for rounding toward zero
+ * @see {@link round} for configurable rounding modes
+ *
  * @category math
  * @since 3.16.0
  */
 export const floor: {
   /**
-   * Calculate the floor of a `BigDecimal` at the given scale.
+   * Computes the floor of a `BigDecimal` at the given scale.
+   *
+   * **When to use**
+   *
+   * Use to round a decimal toward negative infinity at a requested scale.
    *
    * **Example** (Rounding decimals down)
    *
@@ -2688,12 +3270,20 @@ export const floor: {
    * )
    * ```
    *
+   * @see {@link ceil} for rounding toward positive infinity
+   * @see {@link truncate} for rounding toward zero
+   * @see {@link round} for configurable rounding modes
+   *
    * @category math
    * @since 3.16.0
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Calculate the floor of a `BigDecimal` at the given scale.
+   * Computes the floor of a `BigDecimal` at the given scale.
+   *
+   * **When to use**
+   *
+   * Use to round a decimal toward negative infinity at a requested scale.
    *
    * **Example** (Rounding decimals down)
    *
@@ -2711,6 +3301,10 @@ export const floor: {
    * )
    * ```
    *
+   * @see {@link ceil} for rounding toward positive infinity
+   * @see {@link truncate} for rounding toward zero
+   * @see {@link round} for configurable rounding modes
+   *
    * @category math
    * @since 3.16.0
    */