Skip to content

Add KDocs for xs (cross-section) APIs #1995

Description

@zaleslaw

Add KDocs for xs APIs

The file core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/xs.kt has no KDocs at all. Please add concise KDocs for all four functions.

Scope

  • DataFrame<T>.xs(vararg keyValues: Any?) — default-key-columns overload.
  • DataFrame<T>.xs(vararg keyValues: C, keyColumns: ColumnsSelector<T, C>) — explicit key-columns overload.
  • GroupBy<T, G>.xs(vararg keyValues: Any?) — default-key-columns overload.
  • GroupBy<T, G>.xs(vararg keyValues: C, keyColumns: ColumnsSelector<T, C>) — explicit key-columns overload.

KDocs should explain

  • What xs does (cross-section): returns the subset containing only the rows whose key columns match the given keyValues, in order — like fixing the leading key columns to specific values. For DataFrame it returns a filtered DataFrame<T>; for GroupBy it filters within the grouped structure and returns a GroupBy<T, G>.
  • The keyValues → keyColumns positional matching: the i-th keyValues is matched against the i-th selected key column.
  • The default key-column selection (the overloads without keyColumns): the first keyValues.size non-column-group columns at any depth (colsAtAnyDepth().filter { !it.isColumnGroup() }.take(keyValues.size)).
  • That the matched key columns are typically dropped from the result (cross-section semantics) — verify against xsImpl and state the actual behavior.

Test coverage assessment

  • DataFrame.xs has coverage (DataFrameTests.xs, plus usage in DataFrameTreeTests and samples/api/Access.kt).
  • GroupBy.xs has no obvious dedicated test — optional follow-up to add one.

Website coverage

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

Acceptance criteria

  • All four xs overloads have concise KDocs.
  • KDocs explain the cross-section semantics, the positional keyValues↔keyColumns matching, and the default key-column selection.
  • KDocs distinguish the DataFrame result from the GroupBy result.
  • Docs are consistent with the site page xs.html.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

KDocsImprovements or additions to KDocs

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions