updating after first round of reviews

Jolanrensen · Jolanrensen · commit 29975f58e339 · 2023-05-04T16:24:50.000+02:00
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/describe.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/describe.kt
@@ -40,6 +40,7 @@ public fun <T> DataColumn<T>.describe(): DataFrame<ColumnDescription> = describe
 // region DataFrame
 
 public fun <T> DataFrame<T>.describe(): DataFrame<ColumnDescription> = describe { all().recursively(includeGroups = false) }
+
 public fun <T> DataFrame<T>.describe(columns: ColumnsSelector<T, *>): DataFrame<ColumnDescription> =
     describeImpl(getColumnsWithPaths(columns))
 
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/inferType.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/inferType.kt
@@ -12,12 +12,18 @@ import kotlin.reflect.KProperty
 
 public fun AnyCol.inferType(): DataColumn<*> = guessColumnType(name, toList(), type, true)
 
+// region DataFrame
+
 public fun <T> DataFrame<T>.inferType(): DataFrame<T> = inferType { all().recursively(includeGroups = false) }
+
 public fun <T> DataFrame<T>.inferType(columns: ColumnsSelector<T, *>): DataFrame<T> =
     replace(columns).with { it.inferType() }
 
 public fun <T> DataFrame<T>.inferType(vararg columns: String): DataFrame<T> = inferType { columns.toColumnSet() }
+
 public fun <T> DataFrame<T>.inferType(vararg columns: ColumnReference<*>): DataFrame<T> =
     inferType { columns.toColumnSet() }
 
 public fun <T> DataFrame<T>.inferType(vararg columns: KProperty<*>): DataFrame<T> = inferType { columns.toColumnSet() }
+
+// endregion
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/median.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/median.kt
@@ -38,8 +38,8 @@ public inline fun <T, reified R : Comparable<R>> DataColumn<T>.medianOf(noinline
 // region DataRow
 
 public fun AnyRow.rowMedianOrNull(): Any? = Aggregators.median.aggregateMixed(
-        values().filterIsInstance<Comparable<Any?>>().asIterable()
-    )
+    values().filterIsInstance<Comparable<Any?>>().asIterable()
+)
 
 public fun AnyRow.rowMedian(): Any = rowMedianOrNull().suggestIfNull("rowMedian")
 
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/reorder.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/reorder.kt
@@ -21,10 +21,12 @@ public data class Reorder<T, C>(
 }
 
 public fun <T, C> DataFrame<T>.reorder(selector: ColumnsSelector<T, C>): Reorder<T, C> = Reorder(this, selector, false)
+
 public fun <T, C> DataFrame<T>.reorder(vararg columns: ColumnReference<C>): Reorder<T, C> =
     reorder { columns.toColumnSet() }
 
 public fun <T, C> DataFrame<T>.reorder(vararg columns: KProperty<C>): Reorder<T, C> = reorder { columns.toColumnSet() }
+
 public fun <T> DataFrame<T>.reorder(vararg columns: String): Reorder<T, *> = reorder { columns.toColumnSet() }
 
 public fun <T, C, V : Comparable<V>> Reorder<T, C>.by(expression: ColumnExpression<C, V>): DataFrame<T> =
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/replace.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/replace.kt
@@ -38,7 +38,7 @@ public fun <T, C> DataFrame<T>.replace(columns: Iterable<ColumnReference<C>>): R
 
 public fun <T> DataFrame<T>.replaceAll(
     vararg valuePairs: Pair<Any?, Any?>,
-    columns: ColumnsSelector<T, *> = { all().recursively(includeGroups = false) },
+    columns: ColumnsSelector<T, *> = { allRecursively(includeGroups = false) },
 ): DataFrame<T> {
     val map = valuePairs.toMap()
     return update(columns).with { map[it] ?: it }
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/columns/ColumnWithPath.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/columns/ColumnWithPath.kt
@@ -9,12 +9,16 @@ import org.jetbrains.kotlinx.dataframe.impl.columns.depth
 import kotlin.reflect.KProperty
 
 public interface ColumnWithPath<out T> : DataColumn<T> {
-
     public val data: DataColumn<T>
+
     public val path: ColumnPath
+
     public val name: String get() = name()
+
     public val parentName: String? get() = path.parentName
+
     public fun depth(): Int = path.depth()
+
     public fun <C> getChild(accessor: ColumnReference<C>): ColumnWithPath<C>? =
         asColumnGroup().getColumnOrNull(accessor)?.addPath(path + accessor.path())
 
@@ -23,6 +27,7 @@ public interface ColumnWithPath<out T> : DataColumn<T> {
 
     public fun getChild(index: Int): ColumnWithPath<Any?>? =
         asColumnGroup().getColumnOrNull(index)?.addParentPath(path)
+
     public fun <C> getChild(accessor: KProperty<C>): ColumnWithPath<C>? =
         asColumnGroup().getColumnOrNull(accessor)?.addParentPath(path)
 
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/Recursively.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/Recursively.kt
@@ -5,6 +5,11 @@ import org.jetbrains.kotlinx.dataframe.api.isColumnGroup
 import org.jetbrains.kotlinx.dataframe.columns.*
 import org.jetbrains.kotlinx.dataframe.impl.columns.tree.flattenRecursively
 
+/**
+ * Recursively implementation for [TransformableColumnSet].
+ * This converts a [TransformableColumnSet] into a [ColumnSet] by redirecting [ColumnSet.resolve]
+ * to [TransformableColumnSet.transformResolve] with a correctly configured [RecursivelyTransformer].
+ */
 internal fun <C> TransformableColumnSet<C>.recursivelyImpl(
     includeGroups: Boolean = true,
     includeTopLevel: Boolean = true,
@@ -20,6 +25,11 @@ internal fun <C> TransformableColumnSet<C>.recursivelyImpl(
         )
 }
 
+/**
+ * Recursively implementation for [TransformableSingleColumn].
+ * This converts a [TransformableSingleColumn] into a [SingleColumn] by redirecting [SingleColumn.resolveSingle]
+ * to [TransformableSingleColumn.transformResolveSingle] with a correctly configured [RecursivelyTransformer].
+ */
 internal fun <C> TransformableSingleColumn<C>.recursivelyImpl(
     includeGroups: Boolean = true,
     includeTopLevel: Boolean = true,
@@ -35,6 +45,11 @@ internal fun <C> TransformableSingleColumn<C>.recursivelyImpl(
         )
 }
 
+/**
+ * ## Recursively transformer.
+ * A [ColumnSetTransformer] implementation around the [ColumnSet.flattenRecursively] function.
+ * Created only using [recursivelyImpl].
+ */
 private class RecursivelyTransformer(
     val includeGroups: Boolean = true,
     val includeTopLevel: Boolean = true,
@@ -53,6 +68,16 @@ private class RecursivelyTransformer(
         )
 }
 
+/**
+ * Flattens a [ColumnSet]/[SingleColumn] recursively.
+ *
+ * If [this] is a [SingleColumn] containing a single [ColumnGroup], the "top-level" is
+ * considered to be the [ColumnGroup]'s children, otherwise, if this is a [ColumnSet],
+ * the "top-level" is considered to be the columns in the [ColumnSet].
+ *
+ * @param includeGroups Whether to include [ColumnGroup]s in the result.
+ * @param includeTopLevel Whether to include the "top-level" columns in the result.
+ */
 internal fun ColumnSet<*>.flattenRecursively(
     includeGroups: Boolean = true,
     includeTopLevel: Boolean = true,
@@ -65,11 +90,3 @@ internal fun ColumnSet<*>.flattenRecursively(
             .flatMap { it.children().flattenRecursively() }
     }.filter { includeGroups || !it.isColumnGroup() }
 }
-
-internal fun SingleColumn<*>.flattenRecursively(
-    includeGroups: Boolean = true,
-    includeTopLevel: Boolean = true,
-): ColumnSet<*> = (this as ColumnSet<*>).flattenRecursively(
-    includeGroups = includeGroups,
-    includeTopLevel = includeTopLevel,
-)
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/TransformableColumnSet.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/TransformableColumnSet.kt
@@ -20,7 +20,6 @@ import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
  * @see [SingleColumn]
  */
 public interface TransformableColumnSet<out C> : ColumnSet<C> {
-
     public fun transformResolve(
         context: ColumnResolutionContext,
         transformer: ColumnSetTransformer,
@@ -41,15 +40,18 @@ public interface TransformableColumnSet<out C> : ColumnSet<C> {
  * @see [ColumnSet]
  */
 public interface TransformableSingleColumn<out C> : SingleColumn<C> {
-
     public fun transformResolveSingle(
         context: ColumnResolutionContext,
         transformer: ColumnSetTransformer,
     ): ColumnWithPath<C>?
 }
 
+/**
+ * ## Column set transformer.
+ * This contains implementations for both [transform][ColumnSet.transform] and
+ * [transformSingle][SingleColumn.transformSingle] and can be passed around.
+ */
 public interface ColumnSetTransformer {
-
     public fun transform(columnSet: ColumnSet<*>): ColumnSet<*>
 
     public fun transformSingle(singleColumn: SingleColumn<*>): ColumnSet<*>
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/Utils.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/Utils.kt
@@ -78,6 +78,11 @@ internal fun <T> DataColumn<T>.assertIsComparable(): DataColumn<T> {
     return this
 }
 
+/**
+ * Applies a transformation on [this] [SingleColumn] by converting its
+ * single [ColumnWithPath]<[A]> to [List]<[ColumnWithPath]<[B]>] using [converter].
+ * Since [converter] allows you to return multiple columns, the result is turned into a [ColumnSet]<[B]>.
+ */
 internal fun <A, B> SingleColumn<A>.transformSingle(
     converter: (ColumnWithPath<A>) -> List<ColumnWithPath<B>>,
 ): ColumnSet<B> = object : ColumnSet<B> {
@@ -88,6 +93,16 @@ internal fun <A, B> SingleColumn<A>.transformSingle(
             ?: emptyList()
 }
 
+/**
+ * Applies a transformation on [this] by converting its [List]<[ColumnWithPath]<[A]>] to [List]<[ColumnWithPath]<[B]>]
+ * using [converter].
+ *
+ * The result can either be used as a normal [ColumnSet]<[B]>,
+ * which resolves [this] and then applies [converter] on the result,
+ *
+ * or it can be used as a [TransformableColumnSet]<[B]>, where a [ColumnSetTransformer] can be injected before
+ * the [converter] is applied.
+ */
 internal fun <A, B> ColumnSet<A>.transform(
     converter: (List<ColumnWithPath<A>>) -> List<ColumnWithPath<B>>,
 ): TransformableColumnSet<B> = object : TransformableColumnSet<B> {
@@ -105,22 +120,45 @@ internal fun <A, B> ColumnSet<A>.transform(
             .let { converter(it as List<ColumnWithPath<A>>) }
 }
 
+/**
+ * Applies a transformation on [this] by converting its [List]<[ColumnWithPath]<[A]>] to [List]<[ColumnWithPath]<[B]>]
+ * using [converter], but also providing the [ColumnResolutionContext] to the converter.
+ *
+ * The result can either be used as a normal [ColumnSet]<[B]>,
+ * which resolves [this] and then applies [converter] on the result,
+ *
+ * or it can be used as a [TransformableColumnSet]<[B]>, where a [ColumnSetTransformer] can be injected before
+ * the [converter] is applied.
+ */
 internal fun <A, B> ColumnSet<A>.transformWithContext(
     converter: ColumnResolutionContext.(List<ColumnWithPath<A>>) -> List<ColumnWithPath<B>>,
-): ColumnSet<B> = object : ColumnSet<B> {
+): TransformableColumnSet<B> = object : TransformableColumnSet<B> {
     override fun resolve(context: ColumnResolutionContext) =
         this@transformWithContext
             .resolve(context)
             .let { converter(context, it) }
+
+    override fun transformResolve(
+        context: ColumnResolutionContext,
+        transformer: ColumnSetTransformer,
+    ): List<ColumnWithPath<B>> =
+        transformer.transform(this@transformWithContext)
+            .resolve(context)
+            .let { converter(context, it as List<ColumnWithPath<A>>) }
 }
 
+/**
+ * Converts [this] [ColumnSet] to a [SingleColumn].
+ * [resolveSingle] will return the single column of [this] if there is only one, else it will return `null`.
+ * If the result used as a [ColumnSet], `null` will be converted to an empty list.
+ */
 internal fun <T> ColumnSet<T>.singleImpl(): SingleColumn<T> = object : SingleColumn<T> {
     override fun resolveSingle(context: ColumnResolutionContext): ColumnWithPath<T>? =
         this@singleImpl.resolve(context).singleOrNull()
 }
 
 /**
- * Same as [singleImpl], however, if passes any [ColumnSetTransformer] back to [this] if it is supplied.
+ * Same as [singleImpl], however, it passes any [ColumnSetTransformer] back to [this] if it is supplied.
  */
 internal fun <T> TransformableColumnSet<T>.singleWithTransformerImpl(): TransformableSingleColumn<T> =
     object : TransformableSingleColumn<T> {
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt
@@ -74,8 +74,8 @@ internal fun tableJs(columns: List<ColumnDataForJs>, id: Int, rootId: Int, nrow:
     var index = 0
     val data = buildString {
         append("[")
-        fun depthFirstSearch(col: ColumnDataForJs): Int {
-            val children = col.nested.map { depthFirstSearch(it) }
+        fun appendColWithChildren(col: ColumnDataForJs): Int {
+            val children = col.nested.map { appendColWithChildren(it) }
             val colIndex = index++
             val values = col.values.joinToString(",", prefix = "[", postfix = "]") {
                 when (it) {
@@ -100,7 +100,7 @@ internal fun tableJs(columns: List<ColumnDataForJs>, id: Int, rootId: Int, nrow:
 
             return colIndex
         }
-        columns.forEach { depthFirstSearch(it) }
+        columns.forEach { appendColWithChildren(it) }
         append("]")
     }
     val js = getResourceText(
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt
@@ -836,7 +836,8 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      * ## Cols
      * Creates a subset of columns ([ColumnSet]) from the current [ColumnSet].
      *
-     * If the current [ColumnSet] is a [SingleColumn] (and thus consists of only one column (or [column group][ColumnGroup])),
+     * If the current [ColumnSet] is a [SingleColumn]
+     * (and thus consists of only one column (or [column group][ColumnGroup])),
      * then `cols` will create a subset of its children.
      *
      * You can use either a [ColumnFilter] or any of the `vararg` overloads for all
@@ -1966,7 +1967,9 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
         cols { it.name.contains(text) }
 
     public fun SingleColumn<*>.nameContains(regex: Regex): TransformableColumnSet<*> = cols { it.name.contains(regex) }
+
     public fun <C> ColumnSet<C>.nameContains(regex: Regex): TransformableColumnSet<C> = cols { it.name.contains(regex) }
+
     public fun SingleColumn<*>.startsWith(prefix: CharSequence): TransformableColumnSet<*> =
         cols { it.name.startsWith(prefix) }
 
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/replace.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/replace.kt
@@ -38,7 +38,7 @@ public fun <T, C> DataFrame<T>.replace(columns: Iterable<ColumnReference<C>>): R
 
 public fun <T> DataFrame<T>.replaceAll(
     vararg valuePairs: Pair<Any?, Any?>,
-    columns: ColumnsSelector<T, *> = { all().recursively(includeGroups = false) },
+    columns: ColumnsSelector<T, *> = { allRecursively(includeGroups = false) },
 ): DataFrame<T> {
     val map = valuePairs.toMap()
     return update(columns).with { map[it] ?: it }
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/Recursively.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/Recursively.kt
@@ -5,6 +5,11 @@ import org.jetbrains.kotlinx.dataframe.api.isColumnGroup
 import org.jetbrains.kotlinx.dataframe.columns.*
 import org.jetbrains.kotlinx.dataframe.impl.columns.tree.flattenRecursively
 
+/**
+ * Recursively implementation for [TransformableColumnSet].
+ * This converts a [TransformableColumnSet] into a [ColumnSet] by redirecting [ColumnSet.resolve]
+ * to [TransformableColumnSet.transformResolve] with a correctly configured [RecursivelyTransformer].
+ */
 internal fun <C> TransformableColumnSet<C>.recursivelyImpl(
     includeGroups: Boolean = true,
     includeTopLevel: Boolean = true,
@@ -20,6 +25,11 @@ internal fun <C> TransformableColumnSet<C>.recursivelyImpl(
         )
 }
 
+/**
+ * Recursively implementation for [TransformableSingleColumn].
+ * This converts a [TransformableSingleColumn] into a [SingleColumn] by redirecting [SingleColumn.resolveSingle]
+ * to [TransformableSingleColumn.transformResolveSingle] with a correctly configured [RecursivelyTransformer].
+ */
 internal fun <C> TransformableSingleColumn<C>.recursivelyImpl(
     includeGroups: Boolean = true,
     includeTopLevel: Boolean = true,
@@ -35,6 +45,11 @@ internal fun <C> TransformableSingleColumn<C>.recursivelyImpl(
         )
 }
 
+/**
+ * ## Recursively transformer.
+ * A [ColumnSetTransformer] implementation around the [ColumnSet.flattenRecursively] function.
+ * Created only using [recursivelyImpl].
+ */
 private class RecursivelyTransformer(
     val includeGroups: Boolean = true,
     val includeTopLevel: Boolean = true,
@@ -53,6 +68,16 @@ private class RecursivelyTransformer(
         )
 }
 
+/**
+ * Flattens a [ColumnSet]/[SingleColumn] recursively.
+ *
+ * If [this] is a [SingleColumn] containing a single [ColumnGroup], the "top-level" is
+ * considered to be the [ColumnGroup]'s children, otherwise, if this is a [ColumnSet],
+ * the "top-level" is considered to be the columns in the [ColumnSet].
+ *
+ * @param includeGroups Whether to include [ColumnGroup]s in the result.
+ * @param includeTopLevel Whether to include the "top-level" columns in the result.
+ */
 internal fun ColumnSet<*>.flattenRecursively(
     includeGroups: Boolean = true,
     includeTopLevel: Boolean = true,
@@ -65,11 +90,3 @@ internal fun ColumnSet<*>.flattenRecursively(
             .flatMap { it.children().flattenRecursively() }
     }.filter { includeGroups || !it.isColumnGroup() }
 }
-
-internal fun SingleColumn<*>.flattenRecursively(
-    includeGroups: Boolean = true,
-    includeTopLevel: Boolean = true,
-): ColumnSet<*> = (this as ColumnSet<*>).flattenRecursively(
-    includeGroups = includeGroups,
-    includeTopLevel = includeTopLevel,
-)
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/TransformableColumnSet.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/TransformableColumnSet.kt
@@ -20,7 +20,6 @@ import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
  * @see [SingleColumn]
  */
 public interface TransformableColumnSet<out C> : ColumnSet<C> {
-
     public fun transformResolve(
         context: ColumnResolutionContext,
         transformer: ColumnSetTransformer,
@@ -41,15 +40,18 @@ public interface TransformableColumnSet<out C> : ColumnSet<C> {
  * @see [ColumnSet]
  */
 public interface TransformableSingleColumn<out C> : SingleColumn<C> {
-
     public fun transformResolveSingle(
         context: ColumnResolutionContext,
         transformer: ColumnSetTransformer,
     ): ColumnWithPath<C>?
 }
 
+/**
+ * ## Column set transformer.
+ * This contains implementations for both [transform][ColumnSet.transform] and
+ * [transformSingle][SingleColumn.transformSingle] and can be passed around.
+ */
 public interface ColumnSetTransformer {
-
     public fun transform(columnSet: ColumnSet<*>): ColumnSet<*>
 
     public fun transformSingle(singleColumn: SingleColumn<*>): ColumnSet<*>
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/Utils.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/Utils.kt
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt
