Skip to content

Add KDocs for valueCounts APIs #1992

Description

@zaleslaw

Add KDocs for valueCounts APIs

The file core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/valueCounts.kt has no KDocs at all. Please add concise KDocs for the non-deprecated APIs, excluding deprecated / @AccessApiOverload overloads.

Scope

Non-deprecated APIs in valueCounts.kt:

  • The ValueCount @DataSchema interface (count: Int) — the result schema.
  • DataColumn<T>.valueCounts(sort, ascending, dropNA, resultColumn) — returns a DataFrame<ValueCount>.
  • DataFrame<T>.valueCounts(sort, ascending, dropNA, resultColumn, columns) — selector overload.
  • DataFrame<T>.valueCounts(vararg columns: String, sort, ascending, dropNA, resultColumn) — by-name overload.

Out of scope: the deprecated vararg columns: AnyColumnReference / vararg columns: KProperty<*> overloads.

KDocs should explain

  • What valueCounts does: counts the occurrences of each distinct value (for a column) or each distinct row / combination of the selected columns (for a DataFrame), returning a new frame with the distinct values plus a count column.
  • The parameters and their defaults:
    • sort (default true) — whether to sort by count;
    • ascending (default false) — sort direction, i.e. by default most frequent first;
    • dropNA (default true) — whether NA/null values are excluded from counting;
    • resultColumn (default "count") — the name of the count column, and that it is made unique if it clashes with an existing column name (e.g. countcount1);
    • columns — which columns to count distinct combinations of (whole frame if null).
  • The result shape: the value/selected columns are preserved, with the added count column of type Int; the DataFrame result schema is ValueCount-based.

Test coverage assessment

  • There is no dedicated test file for valueCounts.kt; it is only exercised incidentally (samples/api/Analyze.kt, testSets/person/DataColumnTests.kt).
  • Optional follow-up: a focused test file covering sort/ascending, dropNA behavior with nulls, the resultColumn name-clash handling, and multi-column counting.

Website coverage

  • Documented at valueCounts.html; keep KDocs consistent with it.

Acceptance criteria

  • All non-deprecated valueCounts overloads and the ValueCount schema interface have concise KDocs.
  • No documentation is added for the deprecated / @AccessApiOverload overloads.
  • KDocs cover every parameter and its default, the dropNA and count-column-name-clash behavior, and the result shape.
  • Docs are consistent with the site page valueCounts.html.

Metadata

Metadata

Assignees

Labels

KDocsImprovements or additions to KDocstestsSomething related to the JUnit tests, integration tests or testing infrastructure

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions