[Jolanrensen]

Add KDocs for split

Fixes #1471

Added all missing kdocs for split.kt, moved website examples to :samples so they could be reused here.

What

• Added KoDEx-based KDocs to every public, non-deprecated declaration in split.kt. These are the DataFrame.split entry points (selector and vararg String), the Split and SplitWithTransform classes, Split.cast, the ColumnNamesGenerator typealias, default (both overloads), by (the splitter, Char and String delimiter overloads), and the terminals into, inward, intoColumns, intoRows and inplace (all receiver variants: transform / Iterable / DataFrame / Pair), plus DataColumn.splitInto.
  Deprecated / @AccessApiOverload overloads are left undocumented. The already documented by(regex) and match are unchanged.
• SplitDocs KDoc-topic, following gather/GatherDocs. It describes the overall flow: the split { } builder is lazy, then an optional by/match/default step, then a terminal. It also has a clickable Grammar (based on the one on split.html), which every related function links to.
• Reusable snippets in SplitDocs:
  • the lists of splitting and terminal methods;
  • the intermediate-step and terminal-step notes;
  • how many new columns are created and how missing parts are filled (default, otherwise null);
  • the column naming rules: names, then extraNamesGenerator (index starting at 1), then the splitN fallback, plus the numeric suffix added when a name is already taken;
  • the names/extraNamesGenerator params;
  • the type params.
• Shared overload templates (CommonSplitIntoDocs, CommonSplitInwardDocs, CommonSplitIntoRowsDocs, CommonSplitInplaceDocs, SplitByDelimitersDocs). They are filled in through a SplitDocs.PARTS @set argument, so the transform / Iterable / DataFrame overloads differ only in the sentence about how values are split into parts.
• intoRows reuses ExplodeDocs.DropEmptySnippet.

Examples

Following the @sample rule in KDOC_GUIDELINES.md, all examples come from a new samples/.../api/SplitSamples.kt. It has 23 tests, and each one checks its result after // SampleEnd. The samples don't call saveDfHtmlSample(), because no website page uses them yet. Moving the split.html samples out of :core's Modify.kt is left for a separate PR.

Behavior verified while writing (by the sample assertions)

• into puts the new columns at the original column's position and nesting level, which is not always the top level as split.html says. inward nests them in a column group that keeps the original name.
• The number of new columns is max(parts, names.size). Missing parts and null values get the default value (otherwise null).
• intoColumns turns an empty DataFrame value into empty lists.
• intoRows() drops rows with empty lists by default. With dropEmpty = false, such rows are kept with null.

Worth a follow-up (not changed here)

• The existing by(regex) KDoc example writes "\\s+". After KoDEx processing it shows as "\s+", because the escape character is removed.

Good one! Jolanrensen/KoDEx#118

Verification

• ./gradlew :core:processKDocsMain: every @include/@set/@get/@sample resolves, and no tags are left in the generated split.kt.
• ./gradlew :core:ktlintMainSourceSetCheck :samples:ktlintTestSourceSetCheck :core:apiCheck: passes (no API changes).
• ./gradlew :samples:test --tests "org.jetbrains.kotlinx.dataframe.samples.api.SplitSamples": 23/23 pass. The plugin.* consistency tests also pass.
• Generated sources are left to the CI bot.

[jetbrains-air]

Thanks a lot for this, just one blocking fix needed before merge!

Produced by Air Automations. Name: AI Review / Run: https://air.jetbrains.cloud/org/05cf1a7f-6ab5-713b-abd3-29d0c8a05e2d/automations/8daf2412-0b6c-4433-90c0-b40ab5aebcdb?run=1b6cd04c-d063-4f5a-80f2-828701dcdb97

[jetbrains-air]

Nearly there, just one blocking doc fix left before merge!

Produced by Air Automations. Name: AI Review / Run: https://air.jetbrains.cloud/org/05cf1a7f-6ab5-713b-abd3-29d0c8a05e2d/automations/8daf2412-0b6c-4433-90c0-b40ab5aebcdb?run=b03f2dac-cb39-4c8d-b00b-d10cc70d78cd

[jetbrains-air]

Blocking: the last commit changed this to say null values always become null, which is wrong. by maps null to emptyList() (line 608), and splitImpl pads every missing slot with clause.default. So null values get $[MISSING], the same as short values.

Failure: split { a }.by(",").default("-").into(...) fills null rows with "-", but this snippet (included in into/inward) says null. It also contradicts both default KDocs in this file ("as well as null values, get [value]").

Fix: go back to the previous wording, e.g. "null values are split into no parts, so they get $[MISSING] in all new columns."

[jetbrains-air]

Thanks for the update, the HTML is in now; just one blocking fix left before merge!

Produced by Air Automations. Name: AI Review / Run: https://air.jetbrains.cloud/org/05cf1a7f-6ab5-713b-abd3-29d0c8a05e2d/automations/8daf2412-0b6c-4433-90c0-b40ab5aebcdb?run=cb30e272-c5fe-4033-b2ad-d0e3785535c3

[jetbrains-air]

Blocking: the change in the last commit made this wrong. null values do not always become null. by(type, splitter) maps null to emptyList(), and then splitImpl fills every new column with clause.default.

Failure: split { a }.by(',').default("-").into("x", "y") gives "-" in both columns for a null cell. This snippet is included into every into/inward overload and says the result is null. It also contradicts the KDoc of default ("as well as null values, get [value]").

Fix: go back to the previous wording: "null values are split into no parts, so they get $[MISSING] in all new columns."

Produced by Air Automations. Name: AI Review / Run: https://air.jetbrains.cloud/org/05cf1a7f-6ab5-713b-abd3-29d0c8a05e2d/automations/8daf2412-0b6c-4433-90c0-b40ab5aebcdb?run=cb30e272-c5fe-4033-b2ad-d0e3785535c3