Kotlin / Kotlin/dataframe

Add KDocs for non-deprecated `sum` APIs

Open
#1,985 0 comments 0 reactions 1 assignee View on GitHub

@Jolanrensen is already working on this.

Since Jul 24, 2026.

KDocs
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

Add KDocs for non-deprecated sum APIs

The file core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/sum.kt holds the public sum APIs, and the coverage sheet marks the group sum/* as missing KDocs. None of these functions are currently documented (there is only a TODO KDocs comment block at the top of the file). Please add concise KDocs for the current non-deprecated APIs only, excluding deprecated and binary-compatibility (@AccessApiOverload, and the whole // region binary compatibility of DeprecationLevel.HIDDEN overloads) overloads.

Scope

APIs needing KDocs, by receiver:

  • DataColumn.*sum, sumOf
  • DataRow.*rowSum, rowSumOf
  • DataFrame.*sum, sumFor, sumOf
  • Grouped.*sum, sumFor, sumOf
  • Pivot.*sum, sumFor, sumOf
  • PivotGroupBy.*sum, sumFor, sumOf
KDocs should explain
  • What each operation returns:
    • sum — the sum of the values (over the whole column / row / frame);
    • sumFor — a DataRow/DataFrame with a separate sum per selected column;
    • sumOf — the sum of a value computed per row/element via the given expression;
    • the grouped / pivoted variants — sum computed per group / per pivot cell.
  • The common numeric behavior (already captured in the TODO KDocs block, lines 35–42):
    • supported for all primitive number types; for mixed primitive number types the values are unified before summing;
    • nulls are filtered out;
    • the return type is always the same as the input type and never null, except Byte and Short, which are returned as Int;
    • empty input yields 0 in the corresponding number type.
  • The skipNaN parameter: how NaN values in floating-point columns are treated.
  • The separate parameter for the Pivot / PivotGroupBy variants, and the optional name / resultName parameter for the Grouped variants.
  • Note the rowSumOf overloads are split per concrete primitive type (Short/Byte/Int/Long/Float/Double) plus a KType overload, because a single reified T : Number? is not possible — a shared KDoc (e.g. via @include) is fine.
Acceptance criteria
  • Concise KDocs are added to all non-deprecated sum / sumFor / sumOf / rowSum / rowSumOf overloads in sum.kt.
  • No documentation is added for deprecated / @AccessApiOverload overloads, nor for anything in the // region binary compatibility block.
  • KDocs cover the skipNaN parameter, the "same-as-input type, never null" return contract (with the Byte/ShortInt exception), empty-input → 0, and null-filtering.
  • KDocs clearly distinguish the value-returning (sum, sumOf, rowSum*) variants from the per-column aggregation (sumFor) variants.
  • Docs are consistent with the site docs at sum.html.
  • The TODO KDocs comment block at the top of the file is removed once its content has been folded into the actual KDocs.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.