Add KDocs for the four xs overloads (#1995)

[zaleslaw]

Add KDocs for the four xs overloads (#1995)

xs returns a cross-section of a DataFrame or a GroupBy.

All four overloads had no KDoc, and the operation is easy to get wrong: besides filtering rows it also
removes the key columns, and when you pass no selector it picks the key columns
for you — the first n columns, looking inside column groups. GroupBy.xs works on
two sides at once, the keys and the groups. The new docs are built around these
three points.

What changed

File	Change
core/…/api/xs.kt	KDoc for the four overloads. Shared text sits in one KoDEx topic and three snippets, so nothing is copy-pasted per overload.
core/…/documentation/DocumentationUrls.kt	New Xs entry with the link to xs.html.
core/…/test/…/api/xs.kt	New XsTests, 14 tests.
KDOC_GUIDELINES.md	New "Data tables in examples" subsection; note that parameter references must not be used inside KDoc snippets.
KODEX_KDOC_PREPROCESSING.md	Clearer rule on when a tag needs {}.

Examples

Every overload shows the input as a table, then the call and its result — the layout
concatWithKeys already uses. The data and the two DataFrame calls are taken from
the xs page on the documentation website, so the KDoc, the website and the tests
show one example instead of three different ones. The website data has a column group,
which makes the "a group is not counted, its columns are" rule visible instead of only
stated.

Tests

Before this PR xs had DataFrameTests.xs, three scattered cases in
DataFrameTests/DataFrameTreeTests, and one groupBy xs test that only printed its
result. Return types, pairing order and row order were not checked at all, and
GroupBy.xs had no real assertions.

Test	What it pins down
default key columns are the first columns and are removed	Return type DataFrame<T>, removal of the key column, original row order
key values are paired with key columns by position	The i-th value goes to the i-th column; the same values swapped match nothing
a column group is not counted as a key column but its columns are	Counting rule for nested columns
explicit key columns are paired in selection order	Selection order wins over the column order in the frame
number of key values must be equal to the number of key columns	IllegalArgumentException, for three overloads
groupBy xs filters keys and groups and removes the key columns from both	Return type GroupBy<T, G>; the key column is gone from the keys and from the groups
groupBy xs default key columns are the first key columns	Default selection starts at the first grouping key
groupBy xs explicit key columns are paired in selection order	Selection order for GroupBy
groupBy xs key column present only in the keys	A column missing in the groups is ignored there
groupBy xs key column present only in the groups	A column that is not a grouping key filters the groups only
KDoc example - … (4 tests)	Every result table in the KDoc is an expected value here, on the website data, so the tables cannot drift from the code

Return types are asserted with explicit type annotations, so the compiler is the
assertion. Expected values are written out, not computed by a second implementation of
the same logic.

[Copilot]

Pull request overview

Adds comprehensive KDocs and regression coverage for all four xs overloads without changing runtime behavior.

Changes:

• Documents cross-section semantics, key selection, column removal, and examples.
• Adds 14 tests covering ordering, nested columns, errors, and GroupBy.
• Clarifies KoDEx and KDoc authoring guidance.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
KODEX_KDOC_PREPROCESSING.md	Clarifies tag-brace usage.
KDOC_GUIDELINES.md	Adds guidance for parameter references and example tables.
core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/xs.kt	Adds focused xs tests.
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt	Adds the xs documentation URL.
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/xs.kt	Documents all four overloads with shared snippets and examples.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.