Add KDocs and tests for `PivotGroupBy.matches`
- Dominant language
- Kotlin
- Stars
- 1.1k
- Forks
- 83
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 30
Description
## Add KDocs and tests for `PivotGroupBy.matches`
`core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/matches.kt` contains two small public APIs without KDocs:
```kotlin
public fun PivotGroupBy.matches(): DataFrame =
matches(yes = true, no = false)
public fun PivotGroupBy.matches(yes: R, no: R): DataFrame =
aggregate { yes default no }
```
The behavior is already documented on the site through `pivotMatches`:
https://kotlin.github.io/dataframe/pivot.html#pivotmatches
KDocs and tests should be aligned with that documented behavior.
### What it does
`matches()` creates a pivoted `DataFrame` where each cell contains `true` if the pivot value was present in the original data for the corresponding group, and `false` otherwise.
`matches(yes, no)` allows custom values instead of `true` and `false`.
### Scope
- Add concise KDocs for both `matches` overloads.
- Add focused tests for default and custom `yes/no` behavior.
- Align wording with the existing `pivotMatches` documentation.
### Test scenarios as an option
#### Positive scenario
- Given a dataframe grouped by `name` and pivoted by `city`.
- When calling `df.groupBy("name").pivot("city").matches()`.
- Then matching cells contain `true`.
#### Negative / missing-match scenario
- Given a group with no rows for one of the pivot values.
- When calling `matches()`.
- Then the corresponding cell contains `false`.
#### Custom values scenario
- Given the same grouped/pivoted dataframe.
- When calling `matches(yes = "yes", no = "no")`.
- Then matching cells contain `"yes"` and missing cells contain `"no"`.
### Suggested test sketch
```kotlin
@Test
fun `pivot group by matches returns booleans for present values`() {
val df = dataFrameOf("name", "city")(
"Alice", "London",
"Alice", "Paris",
"Bob", "London",
)
val result = df.groupBy("name").pivot("city").matches()
result["city"]["London"].toList() shouldBe listOf(true, true)
result["city"]["Paris"].toList() shouldBe listOf(true, false)
}
@Test
fun `pivot group by matches supports custom yes no values`() {
val df = dataFrameOf("name", "city")(
"Alice", "London",
"Alice", "Paris",
"Bob", "London",
)
val result = df.groupBy("name").pivot("city").matches(yes = "yes", no = "no")
result["city"]["London"].toList() shouldBe listOf("yes", "yes")
result["city"]["Paris"].toList() shouldBe listOf("yes", "no")
}
```
### Acceptance criteria
- `PivotGroupBy.matches()` and `PivotGroupBy.matches(yes, no)` have KDocs.
- KDocs are consistent with the existing `pivotMatches` site documentation.
- Tests verify actual boolean values for matching and missing cells.
- Tests verify custom `yes/no` values.
Contributor guide
Research direction
Start with core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/matches.kt and compare its KDocs with the existing pivotMatches documentation. Locate the focused pivot tests, then cover default boolean and custom yes/no values, including missing matches. Done means both overloads have aligned KDocs and the tests verify matching and missing cells.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- data, documentation, testing-qa
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 85/100