adding number unification docs

Author: Jolanrensen

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/UnifyingNumbers.kt

@@ -40,6 +40,7 @@ import org.jetbrains.kotlinx.dataframe.impl.UnifiedNumberTypeOptions
  *
  * See [UnifiedNumberTypeOptions] for these settings.
  *
- * At the bottom of the graph is [Nothing]. This can be interpreted as `null`.
+ * At the bottom of the graph is [Nothing?][Nothing].
+ * This can be interpreted as `null`.
  */
 public interface UnifyingNumbers

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/UnifyingNumbers.kt

@@ -22,7 +22,8 @@ import org.jetbrains.kotlinx.dataframe.impl.UnifiedNumberTypeOptions
  *
  * See [UnifiedNumberTypeOptions] for these settings.
  *
- * At the bottom of the graph is [Nothing]. This can be interpreted as `null`.
+ * At the bottom of the graph is [Nothing?][Nothing].
+ * This can be interpreted as `null`.
  */
 public interface UnifyingNumbers {
 
@@ -48,5 +49,6 @@ public interface UnifyingNumbers {
      * ```
      */
     @ExcludeFromSources
+    @ExportAsHtml
     private interface Graph
 }

docs/StardustDocs/topics/numberUnification.md

@@ -1,3 +1,44 @@
 [//]: # (title: Number Unification)
 
-// TODO
+The concept of unifying numbers is converting them to a common number type without losing information.
+
+This is an internal part of the library for now, but its logic can be encountered in multiple places, such as
+[statistics](summaryStatistics.md), and [reading JSON](read.md#read-from-json). 
+
+The following graph shows the hierarchy of number types in Kotlin DataFrame.
+
+<inline-frame src="kdocs/org.jetbrains.kotlinx.dataframe.documentation.UnifyingNumbers.Graph.html" />
+
+The order is top-down from the most complex type to the simplest one.
+
+For each number type in the graph, it holds that a number of that type can be expressed lossless by
+a number of a more complex type (any of its parents).
+This is either because the more complex type has a larger range or higher precision (in terms of bits).
+
+Nullability, while not displayed everywhere in the graph, is also taken into account.
+This means that `Int?` and `Float` will be unified to `Double?`.
+
+At the bottom of the graph is `Nothing?`. This can be interpreted as `null`.
+
+> There may be parts of the library that "unify" numbers, such as [`readCsv`](read.md#column-type-inference-from-csv),
+> or [`readExcel`](read.md#read-from-excel).
+> However, because they rely on another library (like [Deephaven CSV](https://github.com/deephaven/deephaven-csv))
+> this may behave slightly differently.
+
+### Unified Number Type Options
+
+There are variants of this graph that exclude some types, such as `BigDecimal` and `BigInteger`, or
+allow some slightly lossy conversions, like from `Long` to `Double`.
+
+This follows either `UnifiedNumberTypeOptions.PRIMITIVES_ONLY` or
+`UnifiedNumberTypeOptions.DEFAULT`.
+
+For `PRIMITIVES_ONLY`, used by [statistics](summaryStatistics.md), big numbers are excluded from the graph.
+Additionally, `Double` is considered the most complex type,
+meaning `Long`/`ULong` and `Double` can be joined to `Double`,
+potentially losing a little precision(!).
+
+For `DEFAULT`, used by [`readJson`](read.md#read-from-json), big numbers can appear.
+`BigDecimal` is considered the most complex type, meaning that `Long`/`ULong` and `Double` will be joined
+to `BigDecimal` instead.
+