Kotlin / Kotlin/dataframe

Add KDocs for pivot `with` APIs

Open Beginner friendly
#1,994 0 comments 0 reactions 0 assignees View on GitHub
KDocs
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

# Add KDocs for pivot `with` APIs

The file `core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/with.kt` has **no KDocs at all**. Please add concise KDocs for all four functions.

### Scope

All four are the pivot aggregation `with(expression)`:

- `Pivot.with(expression: RowExpression): DataRow`
- `ReducedPivot.with(expression: RowExpression): DataRow`
- `PivotGroupBy.with(expression: RowExpression): DataFrame`
- `ReducedPivotGroupBy.with(expression: RowExpression): DataFrame`

### KDocs should explain

- What `with` does: it is a pivot aggregation terminal that fills each pivot cell with the value produced by evaluating `expression` on the group's rows — the result value type `V` is captured via the reified type argument.
- The receiver differences and result shape:
- `Pivot` / `ReducedPivot` produce a single `DataRow` (one value per pivot column);
- `PivotGroupBy` / `ReducedPivotGroupBy` produce a `DataFrame` (a value per group × pivot column);
- the `Reduced*` variants evaluate the expression on the single reduced row of each group/cell, the non-reduced variants over the whole group.
- The `expression` parameter: a `RowExpression` evaluated per group; note (for `ReducedPivotGroupBy`) that returning a column reference resolves to that column's value.

### Test coverage assessment

- There is **no dedicated test file** for `with.kt`. Optional follow-up: cover each receiver variant and the reduced-vs-non-reduced behavior.

### Website coverage

- `with` is covered on `pivot.html` (as a pivot aggregation step); keep KDocs consistent with it.

### Acceptance criteria

- All four `with` overloads have concise KDocs.
- KDocs state the pivot-aggregation semantics, the `DataRow` vs `DataFrame` result per receiver, and the reduced-vs-non-reduced distinction.
- Docs are consistent with the site page `pivot.html`.

Contributor guide

Open the contributing guide

Research direction

Start in core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/with.kt and review all four with overloads. Compare the semantics with the with coverage on pivot.html, including the reduced and non-reduced receiver differences. Done means each overload has concise KDocs describing its expression parameter, pivot-cell aggregation, and DataRow or DataFrame result; no dedicated test file is currently mentioned.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.