Kotlin / Kotlin/dataframe

Add KDocs for `unfold` APIs

Open Beginner friendly
#1,991 0 comments 0 reactions 0 assignees View on GitHub
KDocs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.