Document types package

src/commonMain/kotlin/io/github/kevincianfarini/alchemist/type/Area.kt

@@ -237,8 +237,8 @@ public value class Area internal constructor(private val rawMillimetersSquared:
     }
 
     /**
-     * Returns a fractional string representation of this area expressed in the specified [LengthUnit.International]²
-     * and is rounded to the specified [decimals].
+     * Returns a fractional string representation of this area expressed in the specified [LengthUnit]² and is rounded
+     * to the specified [decimals].
      */
     public fun toString(squareUnit: LengthUnit, decimals: Int = 0): String = when (isInfinite()) {
         true -> rawMillimetersSquared.toString()
@@ -250,8 +250,8 @@ public value class Area internal constructor(private val rawMillimetersSquared:
     }
 
     /**
-     * Returns a fractional string representation of this acceleration expressed in the largest [LengthUnit]² quantity
-     * which is greater than or equal to 1.
+     * Returns a fractional string representation of this area expressed in the largest [LengthUnit]² quantity which is
+     * greater than or equal to 1.
      */
     public override fun toString(): String {
         val largestUnit = LengthUnit.International.entries.asReversed().firstOrNull { squareUnit ->

src/commonMain/kotlin/io/github/kevincianfarini/alchemist/type/Energy.kt

@@ -275,7 +275,7 @@ public value class Energy internal constructor(private val rawMillijoules: Satur
     }
 
     /**
-     * Returns the value of this area expressed as a [Double] number of the specified [unit]. Infinite values are
+     * Returns the value of this energy expressed as a [Double] number of the specified [unit]. Infinite values are
      * converted to either [Double.POSITIVE_INFINITY] or [Double.NEGATIVE_INFINITY] depending on its sign.
      */
     public fun toDouble(unit: EnergyUnit): Double {

src/commonMain/kotlin/io/github/kevincianfarini/alchemist/type/Force.kt

@@ -5,13 +5,21 @@ import io.github.kevincianfarini.alchemist.internal.toDecimalString
 import io.github.kevincianfarini.alchemist.unit.ForceUnit
 import kotlin.jvm.JvmInline
 
+/**
+ * Represents a measure of force and is capable of storing ±9.2 billion newtons at nanonewton precision.
+ */
 @JvmInline
 public value class Force internal constructor(private val rawNanonewtons: SaturatingLong) : Comparable<Force> {
 
     // region SI Arithmetic
 
     /**
      * Returns the resulting [Acceleration] from applying this force to the specified [mass].
+     *
+     * This operation attempts to retain precision, but for sufficiently large values of either this force or the
+     * other [mass], some precision may be lost.
+     *
+     * @throws IllegalArgumentException if both this force and [mass] are infinite.
      */
     public operator fun div(mass: Mass): Acceleration = TODO()
 
@@ -70,6 +78,8 @@ public value class Force internal constructor(private val rawNanonewtons: Satura
 
     /**
      * Returns the number that is the ratio of this and the [other] force value.
+     *
+     * @throws IllegalArgumentException when both this and the [other] force are [infinite][isInfinite].
      */
     public operator fun div(other: Force): Double = rawNanonewtons.toDouble() / other.rawNanonewtons.toDouble()
 
@@ -80,26 +90,40 @@ public value class Force internal constructor(private val rawNanonewtons: Satura
 
     /**
      * Returns a force whose value is this force value divided by the specified [scale].
+     *
+     * @throws IllegalArgumentException when [scale] is equal to [Long.MAX_VALUE] or [Long.MIN_VALUE] and this
+     * force is [infinite][isInfinite].
      */
     public operator fun div(scale: Long): Force = Force(rawNanonewtons / scale)
 
     /**
      * Returns a force whose value is the difference between this and the [other] force value.
+     *
+     * @throws IllegalArgumentException if this force and the [other] force are both
+     * [infinite][isInfinite] but have equivalent signs.
      */
     public operator fun minus(other: Force): Force = Force(rawNanonewtons - other.rawNanonewtons)
 
     /**
      * Returns a force whose value is the sum between this and the [other] force value.
+     *
+     * @throws IllegalArgumentException if this force and the [other] force are both
+     * [infinite][isInfinite] but have differing signs.
      */
     public operator fun plus(other: Force): Force = Force(rawNanonewtons + other.rawNanonewtons)
 
     /**
      * Returns a force whose value is multiplied by the specified [scale].
+     *
+     * @throws IllegalArgumentException when this force is [infinite][isInfinite] and [scale] is 0.
      */
     public operator fun times(scale: Int): Force = times(scale.toLong())
 
     /**
      * Returns a force whose value is multiplied by the specified [scale].
+     *
+     * @throws IllegalArgumentException when this force is [infinite][isInfinite] and [scale] is 0, or when this
+     * force is 0 and scale is [Long.MAX_VALUE] or [Long.MIN_VALUE].
      */
     public operator fun times(scale: Long): Force = Force(rawNanonewtons * scale)
 
@@ -115,10 +139,18 @@ public value class Force internal constructor(private val rawNanonewtons: Satura
         return (rawNanonewtons / unit.nanonewtonScale).rawValue
     }
 
+    /**
+     * Returns the value of this force expressed as a [Double] number of the specified [unit]. Infinite values are
+     * converted to either [Double.POSITIVE_INFINITY] or [Double.NEGATIVE_INFINITY] depending on its sign.
+     */
     public fun toDouble(unit: ForceUnit): Double {
         return rawNanonewtons.toDouble() / unit.nanonewtonScale
     }
 
+    /**
+     * Returns a fractional string representation of this force expressed in the specified [ForceUnit] and is rounded
+     * to the specified [decimals].
+     */
     public fun toString(unit: ForceUnit, decimals: Int = 0): String = when {
         isInfinite() -> rawNanonewtons.toString()
         else -> buildString {
@@ -127,6 +159,10 @@ public value class Force internal constructor(private val rawNanonewtons: Satura
         }
     }
 
+    /**
+     * Returns a fractional string representation of this force expressed in the largest [ForceUnit.International]
+     * quantity which is greater than or equal to 1.
+     */
     public override fun toString(): String {
         val largestUnit = ForceUnit.International.entries.asReversed().firstOrNull { unit ->
             rawNanonewtons / unit.nanonewtonScale > 0
@@ -138,10 +174,21 @@ public value class Force internal constructor(private val rawNanonewtons: Satura
 
     // region Comparisons
 
+    /**
+     * Returns true if this area value is infinite.
+     */
     public fun isInfinite(): Boolean = rawNanonewtons.isInfinite()
 
+    /**
+     * Returns true if this area value is finite.
+     */
     public fun isFinite(): Boolean = rawNanonewtons.isFinite()
 
+    /**
+     * Compares this force with the [other] force. Returns zero if this force is equal
+     * to the specified [other] force, a negative number if it's less than [other], or a positive number
+     * if it's greater than [other].
+     */
     override fun compareTo(other: Force): Int = rawNanonewtons.compareTo(other.rawNanonewtons)
 
     // endregion

src/commonMain/kotlin/io/github/kevincianfarini/alchemist/type/Length.kt

@@ -150,7 +150,7 @@ public value class Length internal constructor(internal val rawNanometers: Satur
      * This operation attempts to retain precision, but for sufficiently large values of either this length or the
      * [other] length, some precision may be lost.
      *
-     * @throws IllegalArgumentException when this energy is [infinite][isInfinite] and [other] is 0 or vice versa.
+     * @throws IllegalArgumentException when this length is [infinite][isInfinite] and [other] is 0 or vice versa.
      */
     public operator fun times(other: Length): Area {
         // Omit micrometer and nanometer components for now. The maximum value these components could ever produce is
@@ -399,7 +399,7 @@ public value class Length internal constructor(internal val rawNanometers: Satur
     }
 
     /**
-     * Returns a fractional string representation of this energy expressed in the largest [LengthUnit.International]
+     * Returns a fractional string representation of this length expressed in the largest [LengthUnit.International]
      * quantity which is greater than or equal to 1.
      */
     public override fun toString(): String {
@@ -414,12 +414,12 @@ public value class Length internal constructor(internal val rawNanometers: Satur
     // region Comparisons
 
     /**
-     * Returns true if this area value is infinite.
+     * Returns true if this length value is infinite.
      */
     public fun isInfinite(): Boolean = rawNanometers.isInfinite()
 
     /**
-     * Returns true if this area value is finite.
+     * Returns true if this length value is finite.
      */
     public fun isFinite(): Boolean = rawNanometers.isFinite()
 

src/commonMain/kotlin/io/github/kevincianfarini/alchemist/type/Mass.kt

@@ -6,13 +6,21 @@ import io.github.kevincianfarini.alchemist.unit.MassUnit
 import kotlin.jvm.JvmInline
 import kotlin.text.Typography.nbsp
 
+/**
+ * Represents a measure of mass and is capable of storing ±9.2 billion kilograms at microgram precision.
+ */
 @JvmInline
 public value class Mass internal constructor(private val rawMicrograms: SaturatingLong) : Comparable<Mass> {
 
     // region SI Arithmetic
 
     /**
      * Returns the [Force] required to apply to this mass to achieve the specified [acceleration].
+     *
+     * This operation attempts to retain precision, but for sufficiently large values of either this mass or the
+     * specified [acceleration], some precision may be lost.
+     *
+     * @throws IllegalArgumentException when [acceleration] is [infinite][isInfinite] and this mass is 0 or vice versa.
      */
     public operator fun times(acceleration: Acceleration): Force = acceleration * this
 
@@ -27,38 +35,61 @@ public value class Mass internal constructor(private val rawMicrograms: Saturati
 
     /**
      * Returns a mass whose value is this mass value divided by the specified [scale].
+     *
+     * @throws IllegalArgumentException when [scale] is equal to [Long.MAX_VALUE] or [Long.MIN_VALUE] and this
+     * mass is [infinite][isInfinite].
      */
     public operator fun div(scale: Long): Mass = Mass(rawMicrograms / scale)
 
     /**
      * Returns the number that is the ratio of this and the [other] mass value.
+     *
+     * @throws IllegalArgumentException when both this and the [other] mass are [infinite][isInfinite].
      */
     public operator fun div(other: Mass): Double = rawMicrograms.toDouble() / other.rawMicrograms.toDouble()
 
     /**
      * Returns a mass whose value is the difference between this and the [other] mass value.
+     *
+     * @throws IllegalArgumentException if this mass and the [other] mass are both
+     * [infinite][isInfinite] but have equivalent signs.
      */
     public operator fun minus(other: Mass): Mass = Mass(rawMicrograms - other.rawMicrograms)
 
     /**
      * Returns a mass whose value is the sum between this and the [other] mass value.
+     *
+     * @throws IllegalArgumentException if this mass and the [other] mass are both
+     * [infinite][isInfinite] but have differing signs.
      */
     public operator fun plus(other: Mass): Mass = Mass(rawMicrograms + other.rawMicrograms)
 
     /**
      * Returns a mass whose value is multiplied by the specified [scale].
+     *
+     * @throws IllegalArgumentException when this mass is [infinite][isInfinite] and [scale] is 0.
      */
     public operator fun times(scale: Int): Mass = times(scale.toLong())
 
     /**
      * Returns a mass whose value is multiplied by the specified [scale].
+     *
+     * @throws IllegalArgumentException when this mass is [infinite][isInfinite] and [scale] is 0, or when this
+     * mass is 0 and scale is [Long.MAX_VALUE] or [Long.MIN_VALUE].
      */
     public operator fun times(scale: Long): Mass = Mass(rawMicrograms * scale)
 
     // endregion
 
     // region Mass to Scalar Conversions
 
+    /**
+     * Splits this mass into teragrams, gigagrams, megagrams, kilograms, grams, milligrams, and micrograms and
+     * executes the [action] with those components. The result of [action] is returned as the result of this function.
+     *
+     * Infinite mass values invoke [action] with [Long.MAX_VALUE] or [Long.MIN_VALUE] for every component, depending
+     * on the infinite value's sign.
+     */
     public fun <T> toInternationalComponents(
         action: (
             teragrams: Long,
@@ -101,10 +132,18 @@ public value class Mass internal constructor(private val rawMicrograms: Saturati
         return (rawMicrograms / unit.microgramScale).rawValue
     }
 
+    /**
+     * Returns the value of this mass expressed as a [Double] number of the specified [unit]. Infinite values are
+     * converted to either [Double.POSITIVE_INFINITY] or [Double.NEGATIVE_INFINITY] depending on its sign.
+     */
     public fun toDouble(unit: MassUnit): Double {
         return rawMicrograms.toDouble() / unit.microgramScale.toDouble()
     }
 
+    /**
+     * Returns a fractional string representation of this mass expressed in the specified [unit] and is rounded
+     * to the specified [decimals].
+     */
     public fun toString(unit: MassUnit, decimals: Int = 0): String = when (isInfinite()) {
         true -> rawMicrograms.toString()
         false -> buildString {
@@ -114,6 +153,10 @@ public value class Mass internal constructor(private val rawMicrograms: Saturati
         }
     }
 
+    /**
+     * Returns a fractional string representation of this mass expressed in the largest [MassUnit.International]
+     * quantity which is greater than or equal to 1.
+     */
     override fun toString(): String {
         val largestUnit = MassUnit.International.entries.asReversed().firstOrNull { unit ->
             rawMicrograms.absoluteValue / unit.microgramScale > 0
@@ -125,10 +168,21 @@ public value class Mass internal constructor(private val rawMicrograms: Saturati
 
     // region Comparisons
 
+    /**
+     * Returns true if this area value is infinite.
+     */
     public fun isInfinite(): Boolean = rawMicrograms.isInfinite()
 
+    /**
+     * Returns true if this area value is finite.
+     */
     public fun isFinite(): Boolean = rawMicrograms.isFinite()
 
+    /**
+     * Compares this mass with the [other] mass. Returns zero if this mass is equal
+     * to the specified [other] mass, a negative number if it's less than [other], or a positive number
+     * if it's greater than [other].
+     */
     override fun compareTo(other: Mass): Int = rawMicrograms.compareTo(other.rawMicrograms)
 
     // endregion