Add KDocs for non-deprecated `single` APIs
- 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
Assessment
This issue has not been assessed yet.