Add KDocs for non-deprecated `std` APIs
- 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
Assessment
This issue has not been assessed yet.