Kotlin / Kotlin/dataframe

Add KDocs for function `Cast` and `CastTo`

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

Description

## Add KDocs, tests, and better site examples for `cast` / `castTo`

`core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/cast.kt` contains public `cast` / `castTo` APIs, but their documentation and tests are uneven.

The site page exists: https://kotlin.github.io/dataframe/cast.html, but examples are minimal and do not clearly cover the main use cases.

### Scope

- Add or improve KDocs for public `cast` / `castTo` overloads in `cast.kt`.
- Make KDocs clear about the difference between:
- unchecked cast-like APIs that only change the formal type
- verified `DataFrame.cast(verify = true)` / `castTo(..., verify = true)` behavior
- Explain that `verify = true` checks schema compatibility but does not perform data conversion.
- Mention `convertTo` as the right API when columns need to be converted to match a schema.
- Improve the site page with clearer examples and data tables, following the style of other API pages.
- Add or improve unit tests for the main overloads and edge cases.

### Test scenarios as an option

#### Successful scenarios

- `DataFrame<*>.cast(verify = false)` changes the formal schema type without validating data.
- `DataFrame<*>.cast(verify = true)` succeeds when the dataframe matches the target schema.
- `DataFrame<*>.castTo(schemaFrom = df, verify = true)` reuses schema from another dataframe.
- `DataFrame<*>.castTo(schemaFrom = ::factory, verify = true)` reuses schema from a function returning a typed dataframe.
- `DataRow<*>.cast(verify = true)` succeeds when the parent dataframe matches the schema.
- Column-level `cast` overloads preserve the same underlying column while changing the formal type.

#### Error scenarios

- `cast(verify = true)` throws when a required column is missing.
- `cast(verify = true)` throws when a column has an incompatible type.
- `cast(verify = true)` throws or rejects incompatible nested column group structure.
- `castTo(..., verify = true)` follows the same validation behavior as `cast(verify = true)`.

### Acceptance criteria

- Public `cast` / `castTo` APIs in `cast.kt` have concise KDocs.
- KDocs distinguish unchecked casts from verified schema checks.
- Site docs contain clearer examples and data tables for `cast` and `castTo`.
- Unit tests cover successful and failing schema verification cases.
- Tests cover at least one `castTo` overload.
- Docs point users to `convertTo` when actual data conversion is needed.

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.