Improve `convert` and `convertTo` pages on site
Nobody has claimed this yet.
- Dominant language
- Kotlin
- Stars
- 1.1k
- Forks
- 83
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 30
Description
Documentation Improvements
Convert
-
Fix the operation grammar at the top of the page: replace the obsolete
to { colExpression }form with the current.asColumn { colExpression }API. -
Add a short
notNullsection with an example for converting nullable columns while preserving nulls. -
Expand
perRowColfrom a grammar-only mention into a documented scenario: use it when conversion needs both the current row and the current column. -
Add a compact “Specialized date/time conversions” section covering
toLocalDate(pattern),toLocalDateTime(format), Java date/time overloads withDateTimeFormatterorlocale, andLong/Inttimestamp conversion withTimeZone. -
Document the current
Instantsituation:toStdlibInstant,toDeprecatedInstant, and the planned migration oftoInstanttokotlin.time.Instant. -
Add examples for less visible supported targets:
toUtcOffset,toYearMonth,toDateTimeComponents,toDuration, andtoJavaDuration. -
Expand
toDataFrames(containsColumns = true)with a small example showing both row-oriented and column-oriented nested lists. -
Add examples for
URL -> IMGandURL -> IFRAME, including parameters such aswidth,height, andborder. -
Mention
cast()briefly if it is intended as a user-facing API for adjusting the static column type before a conversion chain. -
Clarify that
ParserOptionsare only used forString/Charparsing and ignored for non-string source columns.
ConvertTo
-
Make the distinction between
DataFrame.convertTo<Schema>()andDataColumn.convertTo<ValueType>()even more prominent near the top, because the names are easy to confuse. -
Add a short explanation of how
convertTo<Schema>()uses the same automatic conversions asconvert { ... }.to<T>(), linking back to the supported-types list on theconvertpage. -
Add an example showing schema conversion with date/time parser options or a custom parser for date-like strings.
-
Explain precedence more explicitly: custom converters, parsers, and fillers override automatic conversions.
-
Add a small example for
excessiveColumns = ExcessiveColumns.Keepversus dropping or handling columns not present in the target schema. -
Show a nested schema or column-group example, since schema conversion is especially relevant for structured DataFrames.
-
Add a troubleshooting section for common failures: missing required columns, unsupported conversion, parse failure, nullability mismatch, and ambiguous custom converters.
-
Clarify when to use
convertTo<Schema>()instead ofcast<Schema>(),convert { ... }, or manualadd/updateoperations.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the existing Convert and ConvertTo documentation pages and compare their current API examples with the requested APIs, options, and type-conversion behavior. Review the supported-types list and current schema-conversion guidance before updating both pages. Done means the requested examples, distinctions, precedence rules, troubleshooting guidance, and conversion targets are documented accurately.
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
- Mostly clear
- Newbie friendliness
- 64/100