Kotlin / Kotlin/dataframe

Add KDocs for non-deprecated `mean` APIs

Open
#1,972 0 comments 0 reactions 1 assignee Claimed by @Jolanrensen View on GitHub
KDocs
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

## Add KDocs for non-deprecated `mean` APIs

`core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/mean.kt` contains many public `mean` APIs without KDocs.

There is already a TODO in the file describing important behavior that should be reflected in KDocs:

- mean is supported for primitive number types
- `null` values are ignored
- return type is always `Double`
- empty input returns `Double.NaN`, not `null`
- `Long` values may lose precision
- mixed primitive number columns are unified before calculating mean

Please add concise KDocs for the current non-deprecated APIs only. Deprecated overloads and binary-compatibility overloads do not need new KDocs.

### Scope

Add KDocs for non-deprecated overloads in these groups:

- `DataColumn.mean`
- `DataColumn.meanOf`
- `DataRow.rowMean`
- `DataRow.rowMeanOf`
- `DataFrame.mean`
- `DataFrame.meanFor`
- `DataFrame.meanOf`
- `Grouped.mean`
- `Grouped.meanFor`
- `Grouped.meanOf`
- `Pivot.mean`
- `Pivot.meanFor`
- `Pivot.meanOf`
- `PivotGroupBy.mean`
- `PivotGroupBy.meanFor`
- `PivotGroupBy.meanOf`

### KDocs should explain

- What each operation returns:
- mean value as `Double`
- row/dataframe with per-column means
- grouped or pivoted mean values
- Difference between:
- `mean`
- `meanOf`
- `meanFor`
- That only primitive numeric values are supported.
- That `null` values are skipped.
- That empty or all-null input returns `Double.NaN`.
- How `skipNaN` affects floating-point values.
- That mixed primitive number columns are unified before calculating the mean.
- For grouped/pivot variants, that the operation is applied per group or per pivot cell.

### Acceptance criteria

- Non-deprecated public `mean*` APIs have concise KDocs.
- Deprecated and hidden binary-compatibility overloads are not documented.
- KDocs are consistent with the existing site docs:
https://kotlin.github.io/dataframe/mean.html
- KDocs include the behavior currently noted in the TODO comment.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.