Add KDocs (and assess tests/site coverage) for `typeConversions` APIs
- Dominant language
- Kotlin
- Stars
- 1.1k
- Forks
- 83
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 30
Description
# Add KDocs (and assess tests/site coverage) for `typeConversions` APIs
The file `core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/typeConversions.kt` is a large collection of conversion / cast helpers (`toColumn*`, `asColumnGroup`, `asFrameColumn`, `asNumbers`, `castToNullable`, `toValueColumn`, `asGroupBy`, `toMap`, `toDataRow`, array conversions, etc.). It is **partially** documented. Please add concise KDocs for the remaining non-deprecated APIs, excluding deprecated / `@AccessApiOverload` overloads.
### Already documented (leave as-is, or lightly align)
- `SingleColumn.asColumnGroup()` (both overloads) — shared KDoc anchor `SingleColumnAsColumnGroupDocs`.
- The `Infer` enum and its entries (`None`, `Nulls`, `Type`).
- The `NullabilityOptions` enum and its entries (`Infer`, `Checking`, `Widening`).
- `NullabilityOptions.applyNullability(...)`.
### Not documented — scope (grouped)
- **Accessor builders** — `String` / `ColumnPath` / `ColumnReference` / `KProperty` → `toColumnAccessor`, `toColumnOf`, `toColumnGroupAccessor`, `toFrameColumnAccessor`.
- **Type views / casts on columns** — `asNumbers`, `asComparable` (on `DataColumn`, `ColumnSet`, `SingleColumn`), `castToNullable`, `castToNotNullable`, `setNullable`.
- **Column-kind conversions** — `asValueColumn`, `asColumnGroup`, `asFrameColumn`, `asDataColumn`, `asDataFrame`, `FrameColumn.toValueColumn`, `BaseColumn.toDataFrame`.
- **To arrays** — `toTypedArray`, `toFloatArray` / `toDoubleArray` / `toIntArray` / `toLongArray` / `toShortArray` / `toByteArray`.
- **`Iterable` / `Array` → columns/paths** — `toValueColumn`, `toColumn`, `toColumnOf`, `toFrameColumn`, `toColumnGroup` / `toColumnGroupOf`, `toPath`.
- **`DataFrame` / `DataRow` / `Map` conversions** — `DataFrame.toMap`, `DataFrame.asColumnGroup`, `DataFrame.asGroupBy` (all overloads), `DataRow.toDataFrame`, `DataRow.toMap`, `Map.toDataRow`.
- **The `NullabilityException` class.**
### KDocs should explain
- What each helper converts from → to, and whether it is a cheap **cast/view** (no data copied, may throw / be unchecked) or an actual **conversion/copy** — e.g. `asColumnGroup` / `asNumbers` just cast, while `toValueColumn` / `toColumn` build a new column, and `toXxxArray` copy values.
- Requirements / failure modes where relevant (e.g. `asNumbers` requires `isNumber()`, `castToNotNullable` throws if the column has nulls).
- The distinction inside overload families that differ only by receiver (`String` vs `ColumnPath` vs `KProperty`).
- The `infer: Infer` / `name` parameters on the `toColumn` / `toValueColumn` builders.
### Test coverage assessment
- There is **no dedicated test file** for `typeConversions.kt` (no `core/src/test/.../api/typeConversions.kt`).
- These helpers are exercised only **indirectly / incidentally** across many tests (samples like `Create.kt` / `Modify.kt` / `Analyze.kt`, the `testSets/person` suites, `toDataFrame.kt`, etc.).
- Recommendation: treat this ticket as KDocs-first, but note that adding a focused test file covering the non-trivial helpers (`asNumbers`/`asComparable` requirements, `castToNotNullable` on a column with nulls, `toXxxArray`, `asGroupBy`, `toMap`/`toDataRow` round-trip) would be a worthwhile follow-up.
### Website coverage assessment
- There is **no dedicated site page** for these conversions. They appear only fragmentarily on operation pages: `asGroupBy` on `groupBy.html`, various `toColumn` / creation helpers on `createColumn.html`, and mentions in `convert.html`, `ColumnSelectors.html`, `replace.html`.
- Recommendation: KDocs are the primary deliverable here. A small "type conversions / casts" section (or cross-links from `createColumn.html`) could be a follow-up, but is out of scope unless requested.
### Acceptance criteria
- All non-deprecated APIs in `typeConversions.kt` listed under "Not documented" have concise KDocs; the already-documented items are preserved.
- No documentation is added for deprecated / `@AccessApiOverload` overloads.
- KDocs make the cast/view vs conversion/copy distinction explicit and state failure modes (`require`/throws) where they exist.
- The ticket's test-coverage and website findings above are recorded (a follow-up test file / site section may be filed separately).
Contributor guide
Research direction
Start with core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/typeConversions.kt and compare the undocumented APIs with the existing KDocs and exclusions in the issue. Document each listed non-deprecated helper, explaining its source-to-target behavior, cast/view versus copy semantics, parameters, and failure modes. Record the stated test and website coverage findings without adding the proposed follow-up test file or site section.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100