Kotlin / Kotlin/dataframe

Add KDocs for non-deprecated `std` APIs

Open
#1,984 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 `std` APIs

The file `core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/std.kt` holds the public `std` (standard deviation) APIs, and the coverage sheet marks the group `std/*` 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`) overloads.

### Scope

APIs needing KDocs, by receiver:

- `DataColumn.*` — `std`, `stdOf`
- `DataRow.*` — `rowStd`, `rowStdOf`
- `DataFrame.*` — `std`, `stdFor`, `stdOf`
- `Grouped.*` — `std`, `stdFor`, `stdOf`
- `Pivot.*` — `std`, `stdFor`, `stdOf`
- `PivotGroupBy.*` — `std`, `stdFor`, `stdOf`

### KDocs should explain

- What each operation returns:
- `std` — the standard deviation of the values (over the whole column / row / frame);
- `stdFor` — a `DataRow`/`DataFrame` with a separate std per selected column;
- `stdOf` — the std of a value computed per row/element via the given `expression`;
- the grouped / pivoted variants — std computed per group / per pivot cell.
- The common numeric behavior (already captured in the `TODO KDocs` block, lines 26–34):
- supported for all primitive number types; for mixed primitive number types the values are unified before computing;
- `null`s are filtered out;
- the return type is always `Double`, `Double.NaN` for empty input, never `null`;
- may lose precision for `Long`.
- The `ddof` parameter (delta degrees of freedom): defaults to `1` — Bessel's correction, i.e. the "unbiased sample standard deviation" (like R); pass `0` for the "population standard deviation" (like NumPy).
- The `skipNaN` parameter: how `NaN` values in floating-point columns are treated.
- The `separate` parameter for the `Pivot` / `PivotGroupBy` variants, and the optional `name` parameter for the `Grouped` variants.

### Acceptance criteria

- Concise KDocs are added to all non-deprecated `std` / `stdFor` / `stdOf` / `rowStd` / `rowStdOf` overloads in `std.kt`.
- No documentation is added for deprecated / `@AccessApiOverload` overloads.
- KDocs cover the `ddof` (default `1`, Bessel's correction) and `skipNaN` parameters, the `Double` / `Double.NaN` / never-`null` return contract, and null-filtering.
- KDocs clearly distinguish the value-returning (`std`, `stdOf`, `rowStd*`) variants from the per-column aggregation (`stdFor`) variants.
- Docs are consistent with the site docs at `std.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

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.