Add KDocs for pivot `with` APIs
- 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
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