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 builders —
String / ColumnPath / ColumnReference / KProperty → toColumnAccessor, toColumnOf, toColumnGroupAccessor, toFrameColumnAccessor.
- Type views / casts on columns —
asNumbers, asComparable (on DataColumn, ColumnSet, SingleColumn), castToNullable, castToNotNullable, setNullable.
- Column-kind conversions —
asValueColumn, asColumnGroup, asFrameColumn, asDataColumn, asDataFrame, FrameColumn.toValueColumn, BaseColumn.toDataFrame.
- To arrays —
toTypedArray, toFloatArray / toDoubleArray / toIntArray / toLongArray / toShortArray / toByteArray.
Iterable / Array → columns/paths — toValueColumn, toColumn, toColumnOf, toFrameColumn, toColumnGroup / toColumnGroupOf, toPath.
DataFrame / DataRow / Map conversions — DataFrame.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).
Add KDocs (and assess tests/site coverage) for
typeConversionsAPIsThe file
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/typeConversions.ktis 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 /@AccessApiOverloadoverloads.Already documented (leave as-is, or lightly align)
SingleColumn<C>.asColumnGroup()(both overloads) — shared KDoc anchorSingleColumnAsColumnGroupDocs.Inferenum and its entries (None,Nulls,Type).NullabilityOptionsenum and its entries (Infer,Checking,Widening).NullabilityOptions.applyNullability(...).Not documented — scope (grouped)
String/ColumnPath/ColumnReference/KProperty→toColumnAccessor,toColumnOf,toColumnGroupAccessor,toFrameColumnAccessor.asNumbers,asComparable(onDataColumn,ColumnSet,SingleColumn),castToNullable,castToNotNullable,setNullable.asValueColumn,asColumnGroup,asFrameColumn,asDataColumn,asDataFrame,FrameColumn.toValueColumn,BaseColumn.toDataFrame.toTypedArray,toFloatArray/toDoubleArray/toIntArray/toLongArray/toShortArray/toByteArray.Iterable/Array→ columns/paths —toValueColumn,toColumn,toColumnOf,toFrameColumn,toColumnGroup/toColumnGroupOf,toPath.DataFrame/DataRow/Mapconversions —DataFrame.toMap,DataFrame.asColumnGroup,DataFrame.asGroupBy(all overloads),DataRow.toDataFrame,DataRow.toMap,Map.toDataRow.NullabilityExceptionclass.KDocs should explain
asColumnGroup/asNumbersjust cast, whiletoValueColumn/toColumnbuild a new column, andtoXxxArraycopy values.asNumbersrequiresisNumber(),castToNotNullablethrows if the column has nulls).StringvsColumnPathvsKProperty).infer: Infer/nameparameters on thetoColumn/toValueColumnbuilders.Test coverage assessment
typeConversions.kt(nocore/src/test/.../api/typeConversions.kt).Create.kt/Modify.kt/Analyze.kt, thetestSets/personsuites,toDataFrame.kt, etc.).asNumbers/asComparablerequirements,castToNotNullableon a column with nulls,toXxxArray,asGroupBy,toMap/toDataRowround-trip) would be a worthwhile follow-up.Website coverage assessment
asGroupByongroupBy.html, varioustoColumn/ creation helpers oncreateColumn.html, and mentions inconvert.html,ColumnSelectors.html,replace.html.createColumn.html) could be a follow-up, but is out of scope unless requested.Acceptance criteria
typeConversions.ktlisted under "Not documented" have concise KDocs; the already-documented items are preserved.@AccessApiOverloadoverloads.require/throws) where they exist.