effect 3.8.4 → 3.8.5

package/src/BigDecimal.ts

@@ -183,7 +183,34 @@ export const normalize = (self: BigDecimal): BigDecimal => {
  * @since 2.0.0
  * @category scaling
  */
-export const scale = (self: BigDecimal, scale: number): BigDecimal => {
+export const scale: {
+  /**
+   * Scales a given `BigDecimal` to the specified scale.
+   *
+   * If the given scale is smaller than the current scale, the value will be rounded down to
+   * the nearest integer.
+   *
+   * @param self - The `BigDecimal` to scale.
+   * @param scale - The scale to scale to.
+   *
+   * @since 2.0.0
+   * @category scaling
+   */
+  (scale: number): (self: BigDecimal) => BigDecimal
+  /**
+   * Scales a given `BigDecimal` to the specified scale.
+   *
+   * If the given scale is smaller than the current scale, the value will be rounded down to
+   * the nearest integer.
+   *
+   * @param self - The `BigDecimal` to scale.
+   * @param scale - The scale to scale to.
+   *
+   * @since 2.0.0
+   * @category scaling
+   */
+  (self: BigDecimal, scale: number): BigDecimal
+} = dual(2, (self: BigDecimal, scale: number): BigDecimal => {
   if (scale > self.scale) {
     return make(self.value * bigint10 ** BigInt(scale - self.scale), scale)
   }
@@ -193,7 +220,7 @@ export const scale = (self: BigDecimal, scale: number): BigDecimal => {
   }
 
   return self
-}
+})
 
 /**
  * Provides an addition operation on `BigDecimal`s.
@@ -210,7 +237,35 @@ export const scale = (self: BigDecimal, scale: number): BigDecimal => {
  * @category math
  */
 export const sum: {
+  /**
+   * Provides an addition operation on `BigDecimal`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { sum, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(sum(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("5"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
+  /**
+   * Provides an addition operation on `BigDecimal`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { sum, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(sum(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("5"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
   if (that.value === bigint0) {
@@ -247,7 +302,35 @@ export const sum: {
  * @category math
  */
 export const multiply: {
+  /**
+   * Provides a multiplication operation on `BigDecimal`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { multiply, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(multiply(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("6"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
+  /**
+   * Provides a multiplication operation on `BigDecimal`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { multiply, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(multiply(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("6"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
   if (that.value === bigint0 || self.value === bigint0) {
@@ -272,7 +355,35 @@ export const multiply: {
  * @category math
  */
 export const subtract: {
+  /**
+   * Provides a subtraction operation on `BigDecimal`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { subtract, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(subtract(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("-1"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
+  /**
+   * Provides a subtraction operation on `BigDecimal`s.
+   *
+   * @param self - The first operand.
+   * @param that - The second operand.
+   *
+   * @example
+   * import { subtract, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(subtract(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("-1"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
   if (that.value === bigint0) {
@@ -384,7 +495,49 @@ export const roundTerminal = (n: bigint): bigint => {
  * @category math
  */
 export const divide: {
+  /**
+   * Provides a division operation on `BigDecimal`s.
+   *
+   * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
+   * which represents the integer division rounded down to the nearest integer.
+   *
+   * If the divisor is `0`, the result will be `None`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { BigDecimal, Option } from "effect"
+   *
+   * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("3")), Option.some(BigDecimal.unsafeFromString("2")))
+   * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("4")), Option.some(BigDecimal.unsafeFromString("1.5")))
+   * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("0")), Option.none())
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (that: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
+  /**
+   * Provides a division operation on `BigDecimal`s.
+   *
+   * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
+   * which represents the integer division rounded down to the nearest integer.
+   *
+   * If the divisor is `0`, the result will be `None`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.
+   *
+   * @example
+   * import { BigDecimal, Option } from "effect"
+   *
+   * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("3")), Option.some(BigDecimal.unsafeFromString("2")))
+   * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("4")), Option.some(BigDecimal.unsafeFromString("1.5")))
+   * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("0")), Option.none())
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, that: BigDecimal): Option.Option<BigDecimal>
 } = dual(2, (self: BigDecimal, that: BigDecimal): Option.Option<BigDecimal> => {
   if (that.value === bigint0) {
@@ -424,7 +577,47 @@ export const divide: {
  * @category math
  */
 export const unsafeDivide: {
+  /**
+   * Provides an unsafe division operation on `BigDecimal`s.
+   *
+   * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
+   * which represents the integer division rounded down to the nearest integer.
+   *
+   * Throws a `RangeError` if the divisor is `0`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.as
+   *
+   * @example
+   * import { unsafeDivide, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("3")), unsafeFromString("2"))
+   * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("4")), unsafeFromString("1.5"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
+  /**
+   * Provides an unsafe division operation on `BigDecimal`s.
+   *
+   * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
+   * which represents the integer division rounded down to the nearest integer.
+   *
+   * Throws a `RangeError` if the divisor is `0`.
+   *
+   * @param self - The dividend operand.
+   * @param that - The divisor operand.as
+   *
+   * @example
+   * import { unsafeDivide, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("3")), unsafeFromString("2"))
+   * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("4")), unsafeFromString("1.5"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
   if (that.value === bigint0) {
@@ -480,7 +673,39 @@ export const Order: order.Order<BigDecimal> = order.make((self, that) => {
  * @category predicates
  */
 export const lessThan: {
+  /**
+   * Returns `true` if the first argument is less than the second, otherwise `false`.
+   *
+   * @param self - The first argument.
+   * @param that - The second argument.
+   *
+   * @example
+   * import { lessThan, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(lessThan(unsafeFromString("2"), unsafeFromString("3")), true)
+   * assert.deepStrictEqual(lessThan(unsafeFromString("3"), unsafeFromString("3")), false)
+   * assert.deepStrictEqual(lessThan(unsafeFromString("4"), unsafeFromString("3")), false)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (that: BigDecimal): (self: BigDecimal) => boolean
+  /**
+   * Returns `true` if the first argument is less than the second, otherwise `false`.
+   *
+   * @param self - The first argument.
+   * @param that - The second argument.
+   *
+   * @example
+   * import { lessThan, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(lessThan(unsafeFromString("2"), unsafeFromString("3")), true)
+   * assert.deepStrictEqual(lessThan(unsafeFromString("3"), unsafeFromString("3")), false)
+   * assert.deepStrictEqual(lessThan(unsafeFromString("4"), unsafeFromString("3")), false)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.lessThan(Order)
 
@@ -501,7 +726,39 @@ export const lessThan: {
  * @category predicates
  */
 export const lessThanOrEqualTo: {
+  /**
+   * Checks if a given `BigDecimal` is less than or equal to the provided one.
+   *
+   * @param self - The first `BigDecimal` to compare with.
+   * @param that - The second `BigDecimal` to compare with.
+   *
+   * @example
+   * import { lessThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), false)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (that: BigDecimal): (self: BigDecimal) => boolean
+  /**
+   * Checks if a given `BigDecimal` is less than or equal to the provided one.
+   *
+   * @param self - The first `BigDecimal` to compare with.
+   * @param that - The second `BigDecimal` to compare with.
+   *
+   * @example
+   * import { lessThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
+   * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), false)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.lessThanOrEqualTo(Order)
 
@@ -522,7 +779,39 @@ export const lessThanOrEqualTo: {
  * @category predicates
  */
 export const greaterThan: {
+  /**
+   * Returns `true` if the first argument is greater than the second, otherwise `false`.
+   *
+   * @param self - The first argument.
+   * @param that - The second argument.
+   *
+   * @example
+   * import { greaterThan, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(greaterThan(unsafeFromString("2"), unsafeFromString("3")), false)
+   * assert.deepStrictEqual(greaterThan(unsafeFromString("3"), unsafeFromString("3")), false)
+   * assert.deepStrictEqual(greaterThan(unsafeFromString("4"), unsafeFromString("3")), true)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (that: BigDecimal): (self: BigDecimal) => boolean
+  /**
+   * Returns `true` if the first argument is greater than the second, otherwise `false`.
+   *
+   * @param self - The first argument.
+   * @param that - The second argument.
+   *
+   * @example
+   * import { greaterThan, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(greaterThan(unsafeFromString("2"), unsafeFromString("3")), false)
+   * assert.deepStrictEqual(greaterThan(unsafeFromString("3"), unsafeFromString("3")), false)
+   * assert.deepStrictEqual(greaterThan(unsafeFromString("4"), unsafeFromString("3")), true)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.greaterThan(Order)
 
@@ -543,7 +832,39 @@ export const greaterThan: {
  * @category predicates
  */
 export const greaterThanOrEqualTo: {
+  /**
+   * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+   *
+   * @param self - The first `BigDecimal` to compare with.
+   * @param that - The second `BigDecimal` to compare with.
+   *
+   * @example
+   * import { greaterThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), false)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), true)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (that: BigDecimal): (self: BigDecimal) => boolean
+  /**
+   * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+   *
+   * @param self - The first `BigDecimal` to compare with.
+   * @param that - The second `BigDecimal` to compare with.
+   *
+   * @example
+   * import { greaterThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), false)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
+   * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), true)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.greaterThanOrEqualTo(Order)
 
@@ -570,14 +891,63 @@ export const greaterThanOrEqualTo: {
  * @category predicates
  */
 export const between: {
-  (options: {
-    minimum: BigDecimal
-    maximum: BigDecimal
-  }): (self: BigDecimal) => boolean
-  (self: BigDecimal, options: {
-    minimum: BigDecimal
-    maximum: BigDecimal
-  }): boolean
+  /**
+   * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+   *
+   * @param self - The `number` to check.
+   * @param minimum - The `minimum` value to check.
+   * @param maximum - The `maximum` value to check.
+   *
+   * @example
+   * import { BigDecimal } from "effect"
+   *
+   * const between = BigDecimal.between({
+   *   minimum: BigDecimal.unsafeFromString("1"),
+   *   maximum: BigDecimal.unsafeFromString("5") }
+   * )
+   *
+   * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("3")), true)
+   * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("0")), false)
+   * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("6")), false)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
+  (
+    options: {
+      minimum: BigDecimal
+      maximum: BigDecimal
+    }
+  ): (self: BigDecimal) => boolean
+  /**
+   * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+   *
+   * @param self - The `number` to check.
+   * @param minimum - The `minimum` value to check.
+   * @param maximum - The `maximum` value to check.
+   *
+   * @example
+   * import { BigDecimal } from "effect"
+   *
+   * const between = BigDecimal.between({
+   *   minimum: BigDecimal.unsafeFromString("1"),
+   *   maximum: BigDecimal.unsafeFromString("5") }
+   * )
+   *
+   * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("3")), true)
+   * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("0")), false)
+   * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("6")), false)
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
+  (
+    self: BigDecimal,
+    options: {
+      minimum: BigDecimal
+      maximum: BigDecimal
+    }
+  ): boolean
 } = order.between(Order)
 
 /**
@@ -607,14 +977,71 @@ export const between: {
  * @category math
  */
 export const clamp: {
-  (options: {
-    minimum: BigDecimal
-    maximum: BigDecimal
-  }): (self: BigDecimal) => BigDecimal
-  (self: BigDecimal, options: {
-    minimum: BigDecimal
-    maximum: BigDecimal
-  }): BigDecimal
+  /**
+   * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
+   *
+   * - If the `BigDecimal` is less than the `minimum` value, the function returns the `minimum` value.
+   * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
+   * - Otherwise, it returns the original `BigDecimal`.
+   *
+   * @param self - The `BigDecimal` to be clamped.
+   * @param minimum - The lower end of the range.
+   * @param maximum - The upper end of the range.
+   *
+   * @example
+   * import { BigDecimal } from "effect"
+   *
+   * const clamp = BigDecimal.clamp({
+   *   minimum: BigDecimal.unsafeFromString("1"),
+   *   maximum: BigDecimal.unsafeFromString("5") }
+   * )
+   *
+   * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("3")), BigDecimal.unsafeFromString("3"))
+   * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("0")), BigDecimal.unsafeFromString("1"))
+   * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("6")), BigDecimal.unsafeFromString("5"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
+  (
+    options: {
+      minimum: BigDecimal
+      maximum: BigDecimal
+    }
+  ): (self: BigDecimal) => BigDecimal
+  /**
+   * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
+   *
+   * - If the `BigDecimal` is less than the `minimum` value, the function returns the `minimum` value.
+   * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
+   * - Otherwise, it returns the original `BigDecimal`.
+   *
+   * @param self - The `BigDecimal` to be clamped.
+   * @param minimum - The lower end of the range.
+   * @param maximum - The upper end of the range.
+   *
+   * @example
+   * import { BigDecimal } from "effect"
+   *
+   * const clamp = BigDecimal.clamp({
+   *   minimum: BigDecimal.unsafeFromString("1"),
+   *   maximum: BigDecimal.unsafeFromString("5") }
+   * )
+   *
+   * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("3")), BigDecimal.unsafeFromString("3"))
+   * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("0")), BigDecimal.unsafeFromString("1"))
+   * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("6")), BigDecimal.unsafeFromString("5"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
+  (
+    self: BigDecimal,
+    options: {
+      minimum: BigDecimal
+      maximum: BigDecimal
+    }
+  ): BigDecimal
 } = order.clamp(Order)
 
 /**
@@ -632,7 +1059,35 @@ export const clamp: {
  * @category math
  */
 export const min: {
+  /**
+   * Returns the minimum between two `BigDecimal`s.
+   *
+   * @param self - The first `BigDecimal`.
+   * @param that - The second `BigDecimal`.
+   *
+   * @example
+   * import { min, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(min(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("2"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
+  /**
+   * Returns the minimum between two `BigDecimal`s.
+   *
+   * @param self - The first `BigDecimal`.
+   * @param that - The second `BigDecimal`.
+   *
+   * @example
+   * import { min, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(min(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("2"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = order.min(Order)
 
@@ -651,7 +1106,35 @@ export const min: {
  * @category math
  */
 export const max: {
+  /**
+   * Returns the maximum between two `BigDecimal`s.
+   *
+   * @param self - The first `BigDecimal`.
+   * @param that - The second `BigDecimal`.
+   *
+   * @example
+   * import { max, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(max(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("3"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
+  /**
+   * Returns the maximum between two `BigDecimal`s.
+   *
+   * @param self - The first `BigDecimal`.
+   * @param that - The second `BigDecimal`.
+   *
+   * @example
+   * import { max, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(max(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("3"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = order.max(Order)
 
@@ -724,7 +1207,43 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
  * @category math
  */
 export const remainder: {
+  /**
+   * Returns the remainder left over when one operand is divided by a second operand.
+   *
+   * If the divisor is `0`, the result will be `None`.
+   *
+   * @param self - The dividend.
+   * @param divisor - The divisor.
+   *
+   * @example
+   * import { BigDecimal, Option } from "effect"
+   *
+   * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("2"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
+   * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("3"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("1")))
+   * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("-4"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
+  /**
+   * Returns the remainder left over when one operand is divided by a second operand.
+   *
+   * If the divisor is `0`, the result will be `None`.
+   *
+   * @param self - The dividend.
+   * @param divisor - The divisor.
+   *
+   * @example
+   * import { BigDecimal, Option } from "effect"
+   *
+   * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("2"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
+   * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("3"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("1")))
+   * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("-4"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal>
 } = dual(2, (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal> => {
   if (divisor.value === bigint0) {
@@ -754,7 +1273,43 @@ export const remainder: {
  * @category math
  */
 export const unsafeRemainder: {
+  /**
+   * Returns the remainder left over when one operand is divided by a second operand.
+   *
+   * Throws a `RangeError` if the divisor is `0`.
+   *
+   * @param self - The dividend.
+   * @param divisor - The divisor.
+   *
+   * @example
+   * import { unsafeRemainder, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("2"), unsafeFromString("2")), unsafeFromString("0"))
+   * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("3"), unsafeFromString("2")), unsafeFromString("1"))
+   * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("-4"), unsafeFromString("2")), unsafeFromString("0"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (divisor: BigDecimal): (self: BigDecimal) => BigDecimal
+  /**
+   * Returns the remainder left over when one operand is divided by a second operand.
+   *
+   * Throws a `RangeError` if the divisor is `0`.
+   *
+   * @param self - The dividend.
+   * @param divisor - The divisor.
+   *
+   * @example
+   * import { unsafeRemainder, unsafeFromString } from "effect/BigDecimal"
+   *
+   * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("2"), unsafeFromString("2")), unsafeFromString("0"))
+   * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("3"), unsafeFromString("2")), unsafeFromString("1"))
+   * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("-4"), unsafeFromString("2")), unsafeFromString("0"))
+   *
+   * @since 2.0.0
+   * @category math
+   */
   (self: BigDecimal, divisor: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, divisor: BigDecimal): BigDecimal => {
   if (divisor.value === bigint0) {
@@ -788,7 +1343,19 @@ export const Equivalence: equivalence.Equivalence<BigDecimal> = equivalence.make
  * @category predicates
  */
 export const equals: {
+  /**
+   * Checks if two `BigDecimal`s are equal.
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (that: BigDecimal): (self: BigDecimal) => boolean
+  /**
+   * Checks if two `BigDecimal`s are equal.
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (self: BigDecimal, that: BigDecimal): boolean
 } = dual(2, (self: BigDecimal, that: BigDecimal): boolean => Equivalence(self, that))