Kotlin / Kotlin/dataframe

Add KDocs for non-deprecated `single` APIs

Open
#1,982 0 comments 0 reactions 1 assignee Claimed by @zaleslaw View on GitHub
KDocs
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

# Add KDocs for non-deprecated `single` APIs

The file `core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/single.kt` holds public `single` / `singleOrNull` APIs. The value-level (`DataColumn`) and row-level (`DataFrame`) overloads currently have no KDocs, while their `ColumnsSelectionDsl` (`singleCol`) counterparts in the same file are already documented via `CommonSingleDocs`.

Please add concise KDocs for the current non-deprecated APIs only, consistent with the already-documented sibling files `first.kt` and `last.kt`. Deprecated and binary-compatibility overloads are out of scope.

### Scope

APIs needing KDocs (in `single.kt`, regions `// region DataColumn` and `// region DataFrame`):

- `DataColumn.*` — `single()`
- `DataFrame.*` — `single()`, `singleOrNull()`, `single(predicate)`, `singleOrNull(predicate)`

Already documented / out of scope: the `ColumnsSelectionDsl` and `singleCol` overloads, and all deprecated / binary-compatibility overloads.

### KDocs should explain

- What each operation returns:
- `DataColumn.single()` — the single value contained in the column.
- `DataFrame.single()` — the single [row][DataRow] of the frame.
- `single(predicate)` — the single row that satisfies the given row predicate.
- the `*OrNull` variants — the same result, but `null` instead of throwing.
- The difference between the throwing variants and the `*OrNull` variants.
- Empty / non-unique behavior:
- non-null variants throw `NoSuchElementException` when there is no matching element and `IllegalArgumentException` when there is more than one;
- `singleOrNull` returns `null` both when empty and when there is more than one element.
- For the predicate overloads: the predicate is a row expression evaluated per row, and exactly one row must match.
- `See also` cross-links to the related `first` / `last` / `singleOrNull` operations, matching the "See also" blocks used in `first.kt` / `last.kt`.

### Acceptance criteria

- Concise KDocs are added to all non-deprecated `DataColumn` / `DataFrame` `single` and `singleOrNull` overloads in `single.kt`.
- No documentation is added for deprecated or binary-compatibility overloads.
- KDocs state the return value and the exact empty / non-unique behavior (`NoSuchElementException`, `IllegalArgumentException`, or `null`).
- Style and `See also` cross-references are consistent with the already-documented `first.kt` / `last.kt`.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.