Add KDocs for `unfold` APIs
- Dominant language
- Kotlin
- Stars
- 1.1k
- Forks
- 83
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 30
Description
# 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](https://github.com/Kotlin/dataframe/issues/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.unfold(vararg roots: KCallable<*>, maxDepth: Int = 0)`
- `DataFrame.unfold(vararg roots: KCallable<*>, maxDepth: Int = 0, columns: ColumnsSelector)`
- `DataFrame.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 `ColumnGroup`s / `FrameColumn`s 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 #677) if desired, add one test asserting `unfold` stays **consistent with the `Iterable<>.toDataFrame()` overloads**, which #677 noted was never explicitly verified.
Contributor guide
Research direction
Start in core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/unfold.kt and compare the existing API behavior with the unfold.html site page. Add concise KDocs only to the three listed non-deprecated overloads, covering toDataFrame-equivalent expansion, value types remaining unchanged, and roots, maxDepth, and column selection. Confirm the wording against core/src/test/.../api/unfold.kt and ensure deprecated or @AccessApiOverload overloads remain undocumented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100