Add KDocs for `DataFrameGet` accessors
- Dominant language
- Kotlin
- Stars
- 1.1k
- Forks
- 83
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 30
Description
# Add KDocs for `DataFrameGet` accessors
The file `core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/DataFrameGet.kt` is almost entirely undocumented — only `properties()` has a KDoc. Add concise KDocs for the non-deprecated `get*` accessors, excluding deprecated / `@AccessApiOverload` overloads.
### Already documented (leave as-is)
- `DataFrame.properties()`.
### Scope — not documented (grouped)
- **Paths & columns-with-paths (by selector)** — `getColumnsWithPaths`, `getColumnPath`, `getColumnPaths`, `getColumnWithPath`.
- **Get columns** — `getColumns(selector)`, `getColumns(vararg String)`, `getColumnIndex(col)`.
- **Get a single column (`getColumn` family)** — by `name` / `ColumnPath` / `index` / selector, plus the typed `getColumnGroup` (index/name/selector), `getFrameColumn` (path/name), and the `*OrNull` variant `getColumnGroupOrNull(name)`.
- **Get rows** — `getRows(range)`, `getRows(indices)`, `getOrNull(index)`, `rows()`, `rowsReversed()`.
Out of scope: all deprecated `ColumnReference` / `KProperty` overloads of `getColumn` / `getColumnGroup` / `getColumnGroupOrNull` / `containsColumn` / `contains`.
### KDocs should explain
- What each accessor returns and how its argument is interpreted (by **name** vs **`ColumnPath`** vs **index** vs **selector**) — this is what disambiguates the many same-named overloads.
- Failure vs null behavior: the `getColumn*`/`getFrameColumn`/`getColumnGroup` accessors **throw `IllegalArgumentException`** when not found (with the existing precise messages), while `getColumnGroupOrNull` / `getOrNull` return `null`; `getOrNull(index)` returns `null` for out-of-range/negative indices.
- The `.single()` accessors (`getColumnPath`, `getColumnWithPath`): they expect the selector to resolve to **exactly one** column and throw otherwise.
- `rows()` vs `rowsReversed()`: lazy forward/reverse iteration over `DataRow`s.
## Recommendations — make these KDocs genuinely useful (for users *and* for agents reading the source)
1. **First sentence = the contract, self-contained.** IDE quick-doc and LLM/agent context windows both key off the first line. Write "Returns the column at `index` as an `AnyCol`, throwing if out of bounds." — not "Gets a column." Never rely on "see above"; each rendered KDoc must stand alone.
2. **Always document the failure mode with `@throws`.** State the exact exception and the condition (`IllegalArgumentException` when the column/index is absent). For `*OrNull` accessors say explicitly that they return `null` instead. Agents pick the right overload from this alone.
3. **Disambiguate overloads by how the argument selects.** With ~7 `getColumn` overloads sharing a name, the useful information is *name vs path vs index vs selector* and the return type — lead with that so the reader (human or model) knows which one they want.
4. **Cross-link with `@see`.** Pair each throwing accessor with its `*OrNull` sibling and with the underlying `get` / `getColumnOrNull`. Good link graphs are what let an agent traverse the source instead of guessing.
5. **One minimal example per family, not per overload.** Use the canonical `df` receiver and a realistic column name; show the resolved type in a comment (`// ColumnGroup<*>`). Examples are the highest-signal part of a KDoc for both audiences.
6. **Name the concrete return types with links** (`[ColumnGroup]`, `[FrameColumn]`, `[ColumnWithPath]`), not just "a column" — resolvable types beat prose for tooling and for agents resolving symbols.
7. **Call out the non-obvious edge cases** the signature can't show: `getColumnPath`/`getColumnWithPath` require a single match; `getOrNull` tolerates negative indices; `getColumns(vararg String)` returns them in selector order.
8. **Don't restate the signature.** Add the semantics the types don't convey (interpretation, ordering, laziness, throwing). A KDoc that only re-types the signature is noise for both users and agents.
### Acceptance criteria
- All non-deprecated accessors listed under Scope have concise KDocs; `properties()` is preserved.
- Each accessor documents its return type/interpretation and its throw-vs-null behavior (`@throws` or explicit `null`).
- Throwing accessors are `@see`-linked to their `*OrNull` counterparts where they exist.
- No documentation is added for deprecated / `@AccessApiOverload` overloads.
Contributor guide
Research direction
Start in core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/DataFrameGet.kt and review the existing accessor signatures and the KDoc on properties(). Add concise, standalone KDocs only to the listed non-deprecated get* accessors, covering selector interpretation, return types, failure or null behavior, laziness, and relevant @see links. Done means every scoped accessor is documented while deprecated and @AccessApiOverload overloads remain unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100