kdocs, cleaning, and some tiny refactorings

Author: Jolanrensen

core/api/core.api

@@ -23,14 +23,12 @@ import org.jetbrains.kotlinx.dataframe.impl.aggregation.modes.aggregateFor
 import org.jetbrains.kotlinx.dataframe.impl.aggregation.modes.aggregateOf
 import org.jetbrains.kotlinx.dataframe.impl.aggregation.modes.aggregateOfRow
 import org.jetbrains.kotlinx.dataframe.impl.aggregation.primitiveOrMixedNumberColumns
-import org.jetbrains.kotlinx.dataframe.impl.canBeNaN
 import org.jetbrains.kotlinx.dataframe.impl.columns.toNumberColumns
 import org.jetbrains.kotlinx.dataframe.impl.isPrimitiveOrMixedNumber
 import kotlin.experimental.ExperimentalTypeInference
 import kotlin.reflect.KClass
 import kotlin.reflect.KProperty
 import kotlin.reflect.KType
-import kotlin.reflect.full.isSubtypeOf
 import kotlin.reflect.typeOf
 
 /* TODO KDocs

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/sum.kt

@@ -12,32 +12,30 @@ import kotlin.reflect.KType
 import kotlin.reflect.full.withNullability
 
 /**
- * Base interface for all aggregators.
+ * This class is the main entry-point for creating an aggregator.
  *
- * Aggregators are used to compute a single value from an [Iterable] of values, a single [DataColumn],
- * or multiple [DataColumns][DataColumn].
+ * Aggregators are used to compute a single value from a [Sequence] of values,
+ * a single [DataColumn], or multiple [DataColumns][DataColumn].
  *
  * [Aggregator] follows a dependency injection pattern:
  *
  * Using the constructor or [Aggregator.invoke] function, you can create an [Aggregator] instance with a choice of:
- * - [AggregatorAggregationHandler] - the base functionality of the aggregator,
- *   which computes the result from the input values.
+ * - [AggregatorInputHandler] - {@include [AggregatorInputHandler]}
  *
- *   Options: [ReducingAggregationHandler], [SelectingAggregationHandler]
+ *   Options: [NumberInputHandler], [AnyInputHandler]
  *
- * - [AggregatorInputHandler] - the input handler,
- *   which handles specific type checks, conversion, and preprocessing of the input values.
+ * - [AggregatorAggregationHandler] - {@include [AggregatorAggregationHandler]}
  *
- *   Options: [NumberInputHandler], [AnyInputHandler]
+ *   Options: [ReducingAggregationHandler], [SelectingAggregationHandler]
  *
- * - [AggregatorMultipleColumnsHandler] - the multiple columns handler, which specifies how to aggregate multiple columns.
+ * - [AggregatorMultipleColumnsHandler] - {@include [AggregatorMultipleColumnsHandler]}
  *
  *   Options: [FlatteningMultipleColumnsHandler], [TwoStepMultipleColumnsHandler], [NoMultipleColumnsHandler]
  *
- *
- * @param Value The type of the values to be aggregated.
+ * @param Value The non-null type of the values to be aggregated.
  *   The input can always have nulls, they are filtered out.
  * @param Return The type of the resulting value. Can optionally be nullable.
+ * @see [invoke]
  */
 @PublishedApi
 internal class Aggregator<in Value : Any, out Return : Any?>(
@@ -49,13 +47,6 @@ internal class Aggregator<in Value : Any, out Return : Any?>(
     AggregatorMultipleColumnsHandler<Value, Return> by multipleColumnsHandler,
     AggregatorAggregationHandler<Value, Return> by aggregationHandler {
 
-    constructor(other: Aggregator<Value, Return>) : this(
-        name = other.name,
-        aggregationHandler = other,
-        inputHandler = other,
-        multipleColumnsHandler = other,
-    )
-
     // Set the aggregator reference in all handlers to this instance
     init {
         aggregationHandler.init(this)
@@ -73,8 +64,15 @@ internal class Aggregator<in Value : Any, out Return : Any?>(
     override fun toString(): String =
         "Aggregator(name='$name', aggregationHandler=$aggregationHandler, inputHandler=$inputHandler, multipleColumnsHandler=$multipleColumnsHandler)"
 
-    companion object {
-        operator fun <Value : Any, Return : Any?> invoke(
+    internal companion object {
+
+        /**
+         * Factory function for creating an [Aggregator] instance given a name.
+         *
+         * @see AggregatorProvider
+         * @see Aggregator
+         */
+        internal operator fun <Value : Any, Return : Any?> invoke(
             aggregationHandler: AggregatorAggregationHandler<Value, Return>,
             inputHandler: AggregatorInputHandler<Value, Return>,
             multipleColumnsHandler: AggregatorMultipleColumnsHandler<Value, Return>,
@@ -90,18 +88,36 @@ internal class Aggregator<in Value : Any, out Return : Any?>(
     }
 }
 
+/**
+ * Performs aggregation on the given [values], taking [valueType] into account.
+ * If [valueType] is unknown, see [calculateValueType] or [aggregateCalculatingValueType].
+ */
 @PublishedApi
 internal fun <Value : Any, Return : Any?> Aggregator<Value, Return>.aggregate(
     values: Sequence<Value?>,
     valueType: ValueType,
-) = aggregateSingleSequence(values, valueType)
+) = aggregateSequence(values, valueType)
 
+/**
+ * Performs aggregation on the given [values], taking [valueType] into account.
+ * If [valueType] is unknown, see [calculateValueType] or [aggregateCalculatingValueType].
+ */
 @PublishedApi
 internal fun <Value : Any, Return : Any?> Aggregator<Value, Return>.aggregate(
     values: Sequence<Value?>,
     valueType: KType,
-) = aggregate(values, valueType.toValueType())
+) = aggregate(values, valueType.toValueType(needsFullConversion = false))
 
+/**
+ * If the specific [ValueType] of the input is not known, but you still want to call [aggregate],
+ * this function can be called to calculate it by combining the set of known [valueTypes] or
+ * by gathering the types from [values].
+ *
+ * This is a helper function that calls the correct
+ * [AggregatorInputHandler.calculateValueType] based on the given input.
+ *
+ * Giving [valueTypes] is preferred because of efficiency, as it allows for avoiding runtime type checks.
+ */
 internal fun <Value : Any, Return : Any?> Aggregator<Value, Return>.calculateValueType(
     values: Sequence<Value?>,
     valueTypes: Set<KType>? = null,
@@ -111,31 +127,66 @@ internal fun <Value : Any, Return : Any?> Aggregator<Value, Return>.calculateVal
     calculateValueType(values)
 }
 
+/**
+ * If the specific [ValueType] of the input is not known, but you still want to call [aggregate],
+ * this function can be called to calculate it by combining the set of known [valueTypes] or
+ * by gathering the types from [values] and then aggregating them.
+ *
+ * Giving [valueTypes] is preferred because of efficiency, as it allows for avoiding runtime type checks.
+ */
 internal fun <Value : Any, Return : Any?> Aggregator<Value, Return>.aggregateCalculatingValueType(
     values: Sequence<Value?>,
     valueTypes: Set<KType>? = null,
-) = aggregateSingleSequence(
+) = aggregateSequence(
     values = values,
     valueType = calculateValueType(values, valueTypes),
 )
 
+/**
+ * Aggregates the data in the given column and computes a single resulting value.
+ */
 internal fun <Value : Any, Return : Any?> Aggregator<Value, Return>.aggregate(column: DataColumn<Value?>) =
     aggregateSingleColumn(column)
 
+/**
+ * Aggregates the data in the given columns and computes a single resulting value.
+ */
 internal fun <Value : Any, Return : Any?> Aggregator<Value, Return>.aggregate(columns: Sequence<DataColumn<Value?>>) =
     aggregateMultipleColumns(columns)
 
+/**
+ * Gives the index of the aggregation result in the input [values], if it applies.
+ * This is used for aggregators with an [AggregatorAggregationHandler] where
+ * [Value][Value]`  ==  `[Return][Return], and where the result exists in the input.
+ *
+ * Like for [SelectingAggregationHandler].
+ *
+ * Defaults to `-1`.
+ *
+ * If [valueType] is unknown, see [calculateValueType]
+ */
 @PublishedApi
 internal fun <Value : Return & Any, Return : Any?> Aggregator<Value, Return>.indexOfAggregationResult(
     values: Sequence<Value?>,
     valueType: ValueType,
 ): Int = indexOfAggregationResultSingleSequence(values, valueType)
 
+/**
+ * Gives the index of the aggregation result in the input [values], if it applies.
+ * This is used for aggregators with an [AggregatorAggregationHandler] where
+ * [Value][Value]`  ==  `[Return][Return], and where the result exists in the input.
+ *
+ * Like for [SelectingAggregationHandler].
+ *
+ * Defaults to `-1`.
+ *
+ * If [valueType] is unknown, see [calculateValueType]
+ */
 @PublishedApi
 internal fun <Value : Return & Any, Return : Any?> Aggregator<Value, Return>.indexOfAggregationResult(
     values: Sequence<Value?>,
     valueType: KType,
-): Int = indexOfAggregationResultSingleSequence(values, valueType.toValueType())
+): Int = indexOfAggregationResultSingleSequence(values, valueType.toValueType(needsFullConversion = false))
 
 @Suppress("UNCHECKED_CAST")
 @PublishedApi
@@ -146,20 +197,35 @@ internal fun <Type : Any?> Aggregator<*, *>.cast(): Aggregator<Type & Any, Type>
 internal fun <Value : Any, Return : Any?> Aggregator<*, *>.cast2(): Aggregator<Value, Return> =
     this as Aggregator<Value, Return>
 
-/** Type alias for [Aggregator.calculateReturnTypeMultipleColumnsOrNull] */
-internal typealias CalculateReturnTypeOrNull = (type: KType, emptyInput: Boolean) -> KType?
+/**
+ * Type alias for a function that gives the return type of a [Reducer] or [Selector]
+ * given some input type and whether the input is empty.
+ */
+internal typealias CalculateReturnType = (type: KType, emptyInput: Boolean) -> KType
 
 /**
- * Type alias for the argument for [Aggregator.aggregateSingleSequence].
- * Nulls have already been filtered out when this argument is called.
+ * Type alias for a reducer function where the type of the values is provided as [KType].
+ * Nulls have already been filtered out when this function is called.
  */
-internal typealias Reducer<Value, Return> = Sequence<Value & Any>.(type: KType) -> Return
+internal typealias Reducer<Value, Return> = Sequence<Value & Any>.(valueType: KType) -> Return
 
-internal typealias IndexOfResult<Value> = Sequence<Value?>.(type: KType) -> Int
+/**
+ * Type alias for a selector function where the type of the values is provided as [KType].
+ *
+ * It is expected that [Value][Value]`  :  `[Return][Return]`  &  `[Any][Any], and [Return][Return]`  :  `[Any?][Any].
+ *
+ * Nulls have already been filtered out when this function is called.
+ */
+internal typealias Selector<Value, Return> = Sequence<Value & Any>.(type: KType) -> Return
 
-internal typealias IsBetterThanSelector<Value> = (Value & Any).(other: Value & Any, valueType: KType) -> Boolean
+/**
+ * Type alias for a function that returns the index of the result of [Selector] in this sequence.
+ * If the result is not in the sequence, it returns -1.
+ * The type of the values is provided as [KType] and the sequence can contain nulls.
+ */
+internal typealias IndexOfResult<Value> = Sequence<Value?>.(type: KType) -> Int
 
-/** Common case for [CalculateReturnTypeOrNull], preserves return type, but makes it nullable for empty inputs. */
-internal val preserveReturnTypeNullIfEmpty: CalculateReturnTypeOrNull = { type, emptyInput ->
+/** Common case for [CalculateReturnType], preserves return type, but makes it nullable for empty inputs. */
+internal val preserveReturnTypeNullIfEmpty: CalculateReturnType = { type, emptyInput ->
     type.withNullability(emptyInput)
 }

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/Aggregator.kt

@@ -1,48 +1,51 @@
 package org.jetbrains.kotlinx.dataframe.impl.aggregation.aggregators
 
 import org.jetbrains.kotlinx.dataframe.DataColumn
+import org.jetbrains.kotlinx.dataframe.impl.aggregation.aggregators.aggregationHandlers.SelectingAggregationHandler
 import kotlin.reflect.KType
 
+/**
+ * The base functionality of the aggregator,
+ * which defines how the aggregation of a single [Sequence] or [column][DataColumn] is done.
+ * It also provides information on which return type will be given, as [KType], given a [value type][ValueType].
+ * It can also provide the index of the result in the input values if it is a selecting aggregator.
+ */
 @PublishedApi
 internal interface AggregatorAggregationHandler<in Value : Any, out Return : Any?> : AggregatorHandler<Value, Return> {
 
     /**
      * Base function of [Aggregator].
      *
      * Aggregates the given values, taking [valueType] into account,
-     * filtering nulls (only if [type.isMarkedNullable][kotlin.reflect.KType.isMarkedNullable]),
+     * filtering nulls (only if [valueType.type.isMarkedNullable][KType.isMarkedNullable]),
      * and computes a single resulting value.
      *
-     * When using [AggregatorAggregationHandler], this can be supplied by the [AggregatorAggregationHandler.aggregateSingle] argument.
-     *
-     * When the exact [valueType] is unknown, use [aggregateCalculatingValueType].
+     * When the exact [valueType] is unknown, use [calculateValueType] or [aggregateCalculatingValueType].
      */
-    fun aggregateSingleSequence(values: Sequence<Value?>, valueType: ValueType): Return
+    fun aggregateSequence(values: Sequence<Value?>, valueType: ValueType): Return
 
     /**
      * Aggregates the data in the given column and computes a single resulting value.
-     * Calls [aggregateSingleColumn] (with [Iterable] and [kotlin.reflect.KType]).
-     *
-     * See [AggregatorAggregationHandler.aggregateSingleSequence].
+     * Calls [aggregateSequence].
      */
     fun aggregateSingleColumn(column: DataColumn<Value?>): Return
 
     /**
-     * Function that can give the return type of [aggregateSingleSequence] as [kotlin.reflect.KType], given the type of the input.
+     * Function that can give the return type of [aggregateSequence] as [KType], given the type of the input.
      * This allows aggregators to avoid runtime type calculations.
      *
-     * @param type The type of the input values.
+     * @param valueType The type of the input values.
      * @param emptyInput If `true`, the input values are considered empty. This often affects the return type.
-     * @return The return type of [aggregateSingleSequence] as [kotlin.reflect.KType].
+     * @return The return type of [aggregateSequence] as [KType].
      */
-    fun calculateReturnTypeOrNull(type: KType, emptyInput: Boolean): KType?
+    fun calculateReturnType(valueType: KType, emptyInput: Boolean): KType
 
     /**
      * Function that can give the index of the aggregation result in the input [values], if it applies.
      * This is used for [AggregatorAggregationHandlers][AggregatorAggregationHandler] where
      * [Value][Value]`  ==  `[Return][Return], and where the result exists in the input.
      *
-     * Like for [org.jetbrains.kotlinx.dataframe.impl.aggregation.aggregators.aggregationHandlers.SelectingAggregationHandler].
+     * Like for [SelectingAggregationHandler].
      *
      * Defaults to `-1`.
      */

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/AggregatorAggregationHandler.kt

@@ -1,5 +1,12 @@
 package org.jetbrains.kotlinx.dataframe.impl.aggregation.aggregators
 
+/**
+ * Common interface for [Aggregator] handlers or "injector" objects that can build up an [Aggregator] instance.
+ *
+ * When an [Aggregator] is instantiated,
+ * the [init] function of each [AggregatorAggregationHandlers][AggregatorAggregationHandler] is called,
+ * which allows the handler to refer to [Aggregator] instance via [aggregator].
+ */
 internal interface AggregatorHandler<in Value : Any, out Return : Any?> {
 
     /**

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/AggregatorHandler.kt

@@ -2,13 +2,35 @@ package org.jetbrains.kotlinx.dataframe.impl.aggregation.aggregators
 
 import kotlin.reflect.KType
 
+/**
+ * The input handler of the aggregator,
+ * which handles type checks, conversions, and preprocessing of a single sequence of input values.
+ * It can also calculate a specific [value type][ValueType] from the input values or input types
+ * if the (specific) type is not known.
+ */
 internal interface AggregatorInputHandler<in Value : Any, out Return : Any?> : AggregatorHandler<Value, Return> {
 
+    /**
+     * If the specific [ValueType] of the input is not known, but you still want to call [aggregate],
+     * this function can be called to calculate it by combining the set of known [valueTypes].
+     */
     fun calculateValueType(valueTypes: Set<KType>): ValueType
 
-    // heavy!
+    /**
+     * WARNING: HEAVY!
+     *
+     * If the specific [ValueType] of the input is not known, but you still want to call [aggregate],
+     * this function can be called to calculate it by getting the types of [values] at runtime.
+     */
     fun calculateValueType(values: Sequence<Value?>): ValueType
 
+    /**
+     * Preprocesses the input values before aggregation.
+     * It's expected that this function converts [values] to the right [valueType.kType][ValueType.kType]
+     * if [valueType.needsFullConversion][ValueType.needsFullConversion].
+     *
+     * @return A pair of the preprocessed values and the (potentially new) type of the values.
+     */
     fun preprocessAggregation(
         values: Sequence<Value?>,
         valueType: ValueType,

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/AggregatorInputHandler.kt

@@ -1,23 +1,30 @@
 package org.jetbrains.kotlinx.dataframe.impl.aggregation.aggregators
 
 import org.jetbrains.kotlinx.dataframe.DataColumn
+import org.jetbrains.kotlinx.dataframe.impl.aggregation.aggregators.Aggregator
 import kotlin.reflect.KType
 
-internal interface AggregatorMultipleColumnsHandler<in Value : Any, out Return : Any?> : AggregatorHandler<Value, Return> {
+/**
+ * The multiple columns handler,
+ * which specifies how to aggregate multiple columns into a single value by using the supplied
+ * [AggregatorAggregationHandler].
+ * It can also calculate the return type of the aggregation given all input column types.
+ */
+internal interface AggregatorMultipleColumnsHandler<in Value : Any, out Return : Any?> :
+    AggregatorHandler<Value, Return> {
 
     /**
      * Aggregates the data in the multiple given columns and computes a single resulting value.
+     * Calls [Aggregator.aggregateSequence] or [Aggregator.aggregateSingleColumn].
      */
     fun aggregateMultipleColumns(columns: Sequence<DataColumn<Value?>>): Return
 
     /**
-     * Function that can give the return type of [aggregateSingleSequence] with columns as [kotlin.reflect.KType],
-     * given the multiple types of the input.
+     * Function that can give the return type of [aggregateMultipleColumns], given types of the columns.
      * This allows aggregators to avoid runtime type calculations.
      *
      * @param colTypes The types of the input columns.
      * @param colsEmpty If `true`, all the input columns are considered empty. This often affects the return type.
-     * @return The return type of [aggregateSingleSequence] as [kotlin.reflect.KType].
      */
-    fun calculateReturnTypeMultipleColumnsOrNull(colTypes: Set<KType>, colsEmpty: Boolean): KType?
+    fun calculateReturnTypeMultipleColumns(colTypes: Set<KType>, colsEmpty: Boolean): KType
 }