Add KDocs and minimal tests for `parse`
- Dominant language
- Kotlin
- Stars
- 1.1k
- Forks
- 83
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 30
Description
## Add KDocs and minimal tests for `parse`
`core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/parse.kt` contains public `parse` / `tryParse` APIs with incomplete KDocs.
The site page is already strong and should be used as the source of truth for wording and examples:
https://kotlin.github.io/dataframe/parse.html
### Scope
- Add concise KDocs for public non-deprecated APIs in `parse.kt`.
- Reuse the behavior description from the site docs instead of inventing new terminology.
- Add a few minimal tests for the main documented scenarios and negative behavior.
### KDocs should explain
- `parse` parses `String` and `Char` columns into more specific types.
- `DataFrame.parse()` parses all `String` / `Char` columns, including nested columns inside column groups and frame columns.
- `DataFrame.parse { ... }` and `DataFrame.parse("col")` parse only selected columns.
- `parse` is a special case of `convert`.
- Parsing order follows the documented parser order from the site.
- `ParserOptions` can customize locale, date-time parsing, null strings, skipped types, fast double parsing, and experimental parsers.
- If no options are provided, global `DataFrame.parser` options are used.
- `DataColumn.parse()` throws when the column cannot be parsed beyond `String` / `Char`.
- `DataColumn.tryParse()` falls back to the original/string-like result instead of failing in common “cannot guess type” cases.
- `DataColumn?>.parse()` recursively parses nested dataframes.
### Test scenarios as an option
#### Positive scenarios
- `DataFrame.parse()` parses all suitable `String` / `Char` columns:
- `"1"` -> `Int`
- `"true"` / `"FALSE"` -> `Boolean`
- `"a"` remains `Char` or string-like according to parser behavior.
- `DataFrame.parse("column")` parses only the selected column and leaves other string columns unchanged.
- `DataFrame.parse { ... }` parses selected nested columns inside a column group.
- `DataColumn.parse()` parses a numeric string column into a numeric column.
- `DataColumn.parse()` parses numeric chars like `'1'`, `'2'` into integers.
- `ParserOptions(nullStrings = ...)` treats configured strings as `null`.
#### Negative scenarios
- `DataColumn.parse()` throws `IllegalStateException` when the type cannot be guessed and the result would remain `String`.
- `DataColumn.parse()` throws when chars cannot be parsed beyond `Char` / `String`.
- `parse` with `skipTypes` excluding the only suitable target type leaves parsing unable to infer the expected type or falls back according to documented behavior.
### Acceptance criteria
- Public non-deprecated `parse` / `tryParse` APIs have KDocs.
- KDocs link to or reference the site page:
https://kotlin.github.io/dataframe/parse.html
- KDocs are consistent with the documented parser order and `ParserOptions`.
- KDocs clearly distinguish `parse` from `tryParse`.
- KDocs mention dataframe-wide parsing, selected-column parsing, and recursive parsing of nested dataframes.
- Minimal tests cover dataframe-level parsing, selected-column parsing, and column-level parsing.
- At least two negative tests cover “cannot guess type” behavior for `parse`.
- Existing parse tests are preserved.
Contributor guide
Research direction
Start with core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/parse.kt and compare its public non-deprecated APIs with https://kotlin.github.io/dataframe/parse.html. Review the existing parse tests before adding minimal coverage for dataframe-wide, selected-column, nested, and column-level parsing, including at least two cannot-guess-type failures. Done means the KDocs match the documented parser order and ParserOptions behavior, distinguish parse from tryParse, and existing tests remain intact.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- data, documentation, testing
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100