Kotlin / Kotlin/dataframe

Add KDocs for `DataFrameGet` accessors

Open
#1,998 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 `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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.