Skip to content

Add KDocs for unfold APIs #1991

Description

@zaleslaw

Add KDocs for unfold APIs

The file core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/unfold.kt has no KDocs at all. Please add concise KDocs for the non-deprecated APIs, excluding deprecated / @AccessApiOverload overloads.

Context / relation to #677

Issue #677 ("Add tests for unfold") raised two things:

  • Tests — this is now largely done: core/src/test/.../api/unfold.kt (UnfoldTests) covers the basic object-to-columns unfold, maxDepth deep unfolding, "keep value type" (value columns stay untouched), and pair-of-DataFrame / pair-of-@DataSchema structures. So tests are not the primary gap anymore.
  • The isPrimitive()isValueType() rename proposed there appears already resolved: the concept now lives as the internal KClass<*>.isValueType in impl/api/toDataFrame.kt.

What remains missing is documentation on the API itself — hence this KDocs ticket.

Scope

Non-deprecated APIs in unfold.kt:

  • DataColumn<T>.unfold(vararg roots: KCallable<*>, maxDepth: Int = 0)
  • DataFrame<T>.unfold(vararg roots: KCallable<*>, maxDepth: Int = 0, columns: ColumnsSelector<T, *>)
  • DataFrame<T>.unfold(vararg columns: String)

Out of scope: the deprecated vararg columns: AnyColumnReference / vararg columns: KProperty<*> overloads.

KDocs should explain

  • What unfold does: it is the in-DataFrame equivalent of an Iterable<>.toDataFrame() conversion — it takes the selected value column(s) holding objects (or Iterable / DataFrame values) and expands them in place into ColumnGroups / FrameColumns by reading their properties, returning a new DataFrame/column with those columns replaced. (See unfold.html.)
  • That columns holding plain value types are left unchanged (as asserted by the keep value type test).
  • The roots and maxDepth parameters: which properties are traversed and how deep nested objects are expanded (maxDepth = 0 = shallow).
  • The columns selector / vararg String overload: which columns get unfolded.
  • The relationship to toDataFrame (same semantics, applied inside a frame) — and that it is implemented on top of replace(columns).with { ... }.

Acceptance criteria

  • All three non-deprecated unfold overloads have concise KDocs.
  • No documentation is added for the deprecated / @AccessApiOverload overloads.
  • KDocs state the toDataFrame-equivalent semantics, the value-type-kept-as-is behavior, and the meaning of roots / maxDepth.
  • Docs are consistent with the site page unfold.html.
  • (Optional follow-up, per Add tests for unfold #677) if desired, add one test asserting unfold stays consistent with the Iterable<>.toDataFrame() overloads, which Add tests for unfold #677 noted was never explicitly verified.

Metadata

Metadata

Assignees

No one assigned

    Labels

    KDocsImprovements or additions to KDocs

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions