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 keyValueskeyColumns 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 keyValueskeyColumns 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    KDocsImprovements or additions to KDocs

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions