Skip to content

Add KDocs (and assess tests/site coverage) for typeConversions APIs #1990

Description

@zaleslaw

Add KDocs (and assess tests/site coverage) for typeConversions APIs

The file core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/typeConversions.kt is a large collection of conversion / cast helpers (toColumn*, asColumnGroup, asFrameColumn, asNumbers, castToNullable, toValueColumn, asGroupBy, toMap, toDataRow, array conversions, etc.). It is partially documented. Please add concise KDocs for the remaining non-deprecated APIs, excluding deprecated / @AccessApiOverload overloads.

Already documented (leave as-is, or lightly align)

  • SingleColumn<C>.asColumnGroup() (both overloads) — shared KDoc anchor SingleColumnAsColumnGroupDocs.
  • The Infer enum and its entries (None, Nulls, Type).
  • The NullabilityOptions enum and its entries (Infer, Checking, Widening).
  • NullabilityOptions.applyNullability(...).

Not documented — scope (grouped)

  • Accessor buildersString / ColumnPath / ColumnReference / KPropertytoColumnAccessor, toColumnOf, toColumnGroupAccessor, toFrameColumnAccessor.
  • Type views / casts on columnsasNumbers, asComparable (on DataColumn, ColumnSet, SingleColumn), castToNullable, castToNotNullable, setNullable.
  • Column-kind conversionsasValueColumn, asColumnGroup, asFrameColumn, asDataColumn, asDataFrame, FrameColumn.toValueColumn, BaseColumn.toDataFrame.
  • To arraystoTypedArray, toFloatArray / toDoubleArray / toIntArray / toLongArray / toShortArray / toByteArray.
  • Iterable / Array → columns/pathstoValueColumn, toColumn, toColumnOf, toFrameColumn, toColumnGroup / toColumnGroupOf, toPath.
  • DataFrame / DataRow / Map conversionsDataFrame.toMap, DataFrame.asColumnGroup, DataFrame.asGroupBy (all overloads), DataRow.toDataFrame, DataRow.toMap, Map.toDataRow.
  • The NullabilityException class.

KDocs should explain

  • What each helper converts from → to, and whether it is a cheap cast/view (no data copied, may throw / be unchecked) or an actual conversion/copy — e.g. asColumnGroup / asNumbers just cast, while toValueColumn / toColumn build a new column, and toXxxArray copy values.
  • Requirements / failure modes where relevant (e.g. asNumbers requires isNumber(), castToNotNullable throws if the column has nulls).
  • The distinction inside overload families that differ only by receiver (String vs ColumnPath vs KProperty).
  • The infer: Infer / name parameters on the toColumn / toValueColumn builders.

Test coverage assessment

  • There is no dedicated test file for typeConversions.kt (no core/src/test/.../api/typeConversions.kt).
  • These helpers are exercised only indirectly / incidentally across many tests (samples like Create.kt / Modify.kt / Analyze.kt, the testSets/person suites, toDataFrame.kt, etc.).
  • Recommendation: treat this ticket as KDocs-first, but note that adding a focused test file covering the non-trivial helpers (asNumbers/asComparable requirements, castToNotNullable on a column with nulls, toXxxArray, asGroupBy, toMap/toDataRow round-trip) would be a worthwhile follow-up.

Website coverage assessment

  • There is no dedicated site page for these conversions. They appear only fragmentarily on operation pages: asGroupBy on groupBy.html, various toColumn / creation helpers on createColumn.html, and mentions in convert.html, ColumnSelectors.html, replace.html.
  • Recommendation: KDocs are the primary deliverable here. A small "type conversions / casts" section (or cross-links from createColumn.html) could be a follow-up, but is out of scope unless requested.

Acceptance criteria

  • All non-deprecated APIs in typeConversions.kt listed under "Not documented" have concise KDocs; the already-documented items are preserved.
  • No documentation is added for deprecated / @AccessApiOverload overloads.
  • KDocs make the cast/view vs conversion/copy distinction explicit and state failure modes (require/throws) where they exist.
  • The ticket's test-coverage and website findings above are recorded (a follow-up test file / site section may be filed separately).

Metadata

Metadata

Assignees

No one assigned

    Labels

    KDocsImprovements or additions to KDocsdocumentationImprovements or additions to documentation (not KDocs)testsSomething related to the JUnit tests, integration tests or testing infrastructure

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions