Kotlin / Kotlin/dataframe

Improve `convert` and `convertTo` pages on site

Open
#1,956 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

Documentation Improvements

Convert

  1. Fix the operation grammar at the top of the page: replace the obsolete to { colExpression } form with the current .asColumn { colExpression } API.

  2. Add a short notNull section with an example for converting nullable columns while preserving nulls.

  3. Expand perRowCol from a grammar-only mention into a documented scenario: use it when conversion needs both the current row and the current column.

  4. Add a compact “Specialized date/time conversions” section covering toLocalDate(pattern), toLocalDateTime(format), Java date/time overloads with DateTimeFormatter or locale, and Long/Int timestamp conversion with TimeZone.

  5. Document the current Instant situation: toStdlibInstant, toDeprecatedInstant, and the planned migration of toInstant to kotlin.time.Instant.

  6. Add examples for less visible supported targets: toUtcOffset, toYearMonth, toDateTimeComponents, toDuration, and toJavaDuration.

  7. Expand toDataFrames(containsColumns = true) with a small example showing both row-oriented and column-oriented nested lists.

  8. Add examples for URL -> IMG and URL -> IFRAME, including parameters such as width, height, and border.

  9. Mention cast() briefly if it is intended as a user-facing API for adjusting the static column type before a conversion chain.

  10. Clarify that ParserOptions are only used for String/Char parsing and ignored for non-string source columns.

ConvertTo

  1. Make the distinction between DataFrame.convertTo<Schema>() and DataColumn.convertTo<ValueType>() even more prominent near the top, because the names are easy to confuse.

  2. Add a short explanation of how convertTo<Schema>() uses the same automatic conversions as convert { ... }.to<T>(), linking back to the supported-types list on the convert page.

  3. Add an example showing schema conversion with date/time parser options or a custom parser for date-like strings.

  4. Explain precedence more explicitly: custom converters, parsers, and fillers override automatic conversions.

  5. Add a small example for excessiveColumns = ExcessiveColumns.Keep versus dropping or handling columns not present in the target schema.

  6. Show a nested schema or column-group example, since schema conversion is especially relevant for structured DataFrames.

  7. Add a troubleshooting section for common failures: missing required columns, unsupported conversion, parse failure, nullability mismatch, and ambiguous custom converters.

  8. Clarify when to use convertTo<Schema>() instead of cast<Schema>(), convert { ... }, or manual add/update operations.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.