Add cumSum function for DataColumn, DataFrame, and GroupBy

Introduces a cumSum operation to compute cumulative sums with options to skip null values. Documentation and overloads are added for DataColumn, DataFrame, and GroupBy, ensuring consistency across API components. This update enhances support for common data aggregation workflows.

Author: zaleslaw

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

@@ -5,7 +5,10 @@ import org.jetbrains.kotlinx.dataframe.ColumnsSelector
 import org.jetbrains.kotlinx.dataframe.DataColumn
 import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
+import org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions
 import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
+import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls
+import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
 import org.jetbrains.kotlinx.dataframe.impl.nothingType
 import org.jetbrains.kotlinx.dataframe.impl.nullableNothingType
 import org.jetbrains.kotlinx.dataframe.math.cumSum
@@ -18,6 +21,36 @@ import kotlin.reflect.typeOf
 
 // region DataColumn
 
+/**
+ * ## The CumSum Operation
+ *
+ * Computes the cumulative sum of the values in the {@get DATA_TYPE}.
+ *
+ * __NOTE:__ If the column contains nullable values and `skipNA` is set to `true`,
+ * skips null values when computing the cumulative sum.
+ * Otherwise, any null value encountered will propagate null values in the output from that point onward.
+ *
+ * {@get [CUMSUM_PARAM] @param [columns]
+ * The names of the columns to apply cumSum operation.}
+ *
+ * @param [skipNA] Whether to skip null values (default: `true`).
+ *
+ * @return A new {@get DATA_TYPE} of the same type with the cumulative sum of the values.
+ *
+ * {@get [CUMSUM_PARAM] @see [Selecting Columns][SelectSelectingOptions].}
+ * @see {@include [DocumentationUrls.CumSum]}
+ */
+@ExcludeFromSources
+@Suppress("ClassName")
+private interface CumSumDocs {
+    interface CUMSUM_PARAM
+}
+
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [DataColumn]}.
+ * {@set [CumSumDocs.CUMSUM_PARAM]}
+ */
 public fun <T : Number?> DataColumn<T>.cumSum(skipNA: Boolean = defaultCumSumSkipNA): DataColumn<T> =
     when (type()) {
         typeOf<Double>() -> cast<Double>().cumSum(skipNA).cast()
@@ -79,25 +112,46 @@ private val supportedClasses = setOf(
 
 // region DataFrame
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [DataFrame]}.
+ */
 public fun <T, C> DataFrame<T>.cumSum(
     skipNA: Boolean = defaultCumSumSkipNA,
     columns: ColumnsSelector<T, C>,
 ): DataFrame<T> =
     convert(columns).to { if (it.typeClass in supportedClasses) it.cast<Number?>().cumSum(skipNA) else it }
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [DataFrame]}.
+ */
 public fun <T> DataFrame<T>.cumSum(vararg columns: String, skipNA: Boolean = defaultCumSumSkipNA): DataFrame<T> =
     cumSum(skipNA) { columns.toColumnSet() }
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [DataFrame]}.
+ */
 @AccessApiOverload
 public fun <T> DataFrame<T>.cumSum(
     vararg columns: AnyColumnReference,
     skipNA: Boolean = defaultCumSumSkipNA,
 ): DataFrame<T> = cumSum(skipNA) { columns.toColumnSet() }
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [DataFrame]}.
+ */
 @AccessApiOverload
 public fun <T> DataFrame<T>.cumSum(vararg columns: KProperty<*>, skipNA: Boolean = defaultCumSumSkipNA): DataFrame<T> =
     cumSum(skipNA) { columns.toColumnSet() }
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [DataFrame]}.
+ * {@set [CumSumDocs.CUMSUM_PARAM]}
+ */
 public fun <T> DataFrame<T>.cumSum(skipNA: Boolean = defaultCumSumSkipNA): DataFrame<T> =
     cumSum(skipNA) {
         colsAtAnyDepth { !it.isColumnGroup() }
@@ -107,26 +161,47 @@ public fun <T> DataFrame<T>.cumSum(skipNA: Boolean = defaultCumSumSkipNA): DataF
 
 // region GroupBy
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [GroupBy]}.
+ */
 public fun <T, G, C> GroupBy<T, G>.cumSum(
     skipNA: Boolean = defaultCumSumSkipNA,
     columns: ColumnsSelector<G, C>,
 ): GroupBy<T, G> = updateGroups { cumSum(skipNA, columns) }
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [GroupBy]}.
+ */
 public fun <T, G> GroupBy<T, G>.cumSum(vararg columns: String, skipNA: Boolean = defaultCumSumSkipNA): GroupBy<T, G> =
     cumSum(skipNA) { columns.toColumnSet() }
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [GroupBy]}.
+ */
 @AccessApiOverload
 public fun <T, G> GroupBy<T, G>.cumSum(
     vararg columns: AnyColumnReference,
     skipNA: Boolean = defaultCumSumSkipNA,
 ): GroupBy<T, G> = cumSum(skipNA) { columns.toColumnSet() }
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [GroupBy]}.
+ */
 @AccessApiOverload
 public fun <T, G> GroupBy<T, G>.cumSum(
     vararg columns: KProperty<*>,
     skipNA: Boolean = defaultCumSumSkipNA,
 ): GroupBy<T, G> = cumSum(skipNA) { columns.toColumnSet() }
 
+/**
+ * {@include [CumSumDocs]}
+ * {@set DATA_TYPE [GroupBy]}.
+ * {@set [CumSumDocs.CUMSUM_PARAM]}
+ */
 public fun <T, G> GroupBy<T, G>.cumSum(skipNA: Boolean = defaultCumSumSkipNA): GroupBy<T, G> =
     cumSum(skipNA) {
         colsAtAnyDepth { !it.isColumnGroup() }

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

@@ -80,4 +80,7 @@ internal interface DocumentationUrls {
 
     /** <a href="{@include [Url]}/distinct.html">See `distinct` on the documentation website.</a> */
     interface Distinct
+
+    /** <a href="{@include [Url]}/cumsum.html">See `cumSum` on the documentation website.</a> */
+    interface CumSum
 }