Add KDocs for function `Cast` and `CastTo`
- 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
Assessment
This issue has not been assessed yet.