Improve `inferType` documentation, KDocs, and test coverage

Inizia da core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/inferType.kt e dal test esistente in core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/inferType.kt, quindi aggiorna docs/StardustDocs/topics/inferType.md. Esegui i test inferType esistenti prima di ampliare la copertura per gli overload e gli scenari elencati. Il lavoro è completato quando il sito web e KDocs spiegano l’inferenza basata sul runtime e i suoi limiti, e i test coprono i comportamenti indicati.

Improve inferType documentation, KDocs, and test coverage

Context

inferType is useful when a column keeps a wider type than the values currently stored in it require.

Typical cases:

• after filter, when a column originally typed as Any?, Comparable<*>, or Number? now contains only values of a more specific type;
• after manual transformations such as convert(...).with(Infer.None);
• after reading or constructing loosely typed data where columns initially have broad types;
• before schema-sensitive operations that benefit from more precise column types, such as colsOf<T>(), convertTo<Schema>(), typed accessors, schema checks, or serialization.

Important distinction: inferType does not parse or convert values. It only refines the column type based on already stored runtime values. For example, it may refine Any? to Int? if the values are already integers, but it will not convert "123" to Int.

Current website page:
https://kotlin.github.io/dataframe/infertype.html

Current source:
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/inferType.kt

Current docs source:
docs/StardustDocs/topics/inferType.md

Existing tests:
core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/inferType.kt

Problem

The current website page is too short and does not explain when inferType is useful in real DataFrame workflows.

The public API also has little or no KDoc, even though the behavior has important nuances:

• inference is based on existing runtime values;
• the result is the nearest common supertype of the values;
• inference is constrained by the current column type upper bound via TypeSuggestion.InferWithUpperbound(type);
• DataFrame.inferType() applies to non-column-group columns at any depth;
• inferType is not parsing and should be distinguished from parse and convert.

The existing tests cover only a narrow subset of behavior.

Acceptance Criteria

• The inferType website page explains why the operation exists and when users should consider it.
• The website clearly states that inferType does not parse or convert values.
• The website includes examples for whole-DataFrame inference, selected-column inference, and post-filter type refinement.
• Public non-deprecated inferType functions have KDocs.
• KDocs mention runtime-value-based inference, nearest common supertype behavior, and the current type upper bound.
• KDocs explain the default behavior of DataFrame.inferType().
• Tests cover all non-deprecated public overloads.
• Tests cover nullable values, selected columns, whole-DataFrame inference, nested columns, and broad-to-specific type refinement.
• Tests include at least one scenario demonstrating that strings are not parsed into numbers by inferType.

Website Recommendations

1. Add a “When to use it” section

Explain that inferType is useful when values have become more specific than the column type.

Suggested example:

val col by columnOf<Comparable<*>>("Alice", 1, 3.5)

val strings = col.filter { it is String }

strings.type()              // Comparable<*>
strings.inferType().type()  // String

2. Add a “What it does not do” section

Clarify that inferType does not parse or transform values.

Suggested example:

val col by columnOf<Any?>("1", "2", "3")

col.inferType().type() // String?, not Int?

For converting strings to numbers, point users to parse or convert.

3. Document whole-DataFrame behavior

Explain that:

df.inferType()

infers types for non-column-group columns at any depth.

Mention that column groups themselves are not replaced by inferred value columns.

4. Document selected-column behavior

Show both name-based and selector-based usage:

df.inferType("value")

df.inferType {
    colsOf<Any?>()
}

5. Add a schema-sensitive workflow example

Show why type refinement is useful before operations that depend on column types:

val refined = df.inferType("value")

refined.select { colsOf<Int?>() }

6. Link to related operations

Add a short “See also” section:

• parse for parsing string values into typed values
• convert for explicit conversion
• convertTo<Schema>() for schema conversion

KDoc Recommendations

Add KDocs to:

public fun AnyCol.inferType(): DataColumn<*>
public fun <T> DataFrame<T>.inferType(): DataFrame<T>
public fun <T> DataFrame<T>.inferType(columns: ColumnsSelector<T, *>): DataFrame<T>
public fun <T> DataFrame<T>.inferType(vararg columns: String): DataFrame<T>

Suggested KDoc topics:

• The operation refines column types based on already stored runtime values.
• It does not parse strings or convert values.
• The resulting type is the nearest common supertype of the current values.
• The inferred type is constrained by the current column type as an upper bound.
• DataFrame.inferType() applies to all non-column-group columns at any depth.
• Selected-column overloads preserve column names and positions.
• Typical use cases include post-filter narrowing, loosely typed input data, and recovery after transformations that intentionally disabled inference.

Test Scenarios

1. AnyCol.inferType() narrows after filtering

Existing scenario can stay:

val col by columnOf<Comparable<*>>("Alice", 1, 3.5)
val filtered = col.filter { it is String }

filtered.inferType().type() shouldBe typeOf<String>()

2. DataFrame.inferType("column") narrows a selected column

Create a DataFrame with two broad columns and verify that only the named column is refined.

3. DataFrame.inferType { ... } narrows selector-matched columns

Use a selector such as colsOf<Any?>() or a name predicate and verify only selected columns are affected.

4. DataFrame.inferType() applies to non-column-group columns at any depth

Create a DataFrame with a nested column group containing broad typed value columns. Verify nested value columns are refined, while the column group structure is preserved.

5. Nullable values preserve nullability

Example expectation:

val col by columnOf<Any?>(1, null, 2)

col.inferType().type() shouldBe typeOf<Int?>()

6. Mixed values infer nearest common supertype

Example:

val col by columnOf<Any?>(1, 2.0)

col.inferType().type()

Verify the expected common type according to the library’s type inference rules.

7. inferType does not parse strings

Example:

val col by columnOf<Any?>("1", "2", "3")

col.inferType().type() shouldBe typeOf<String?>()

Also verify the values remain strings.

8. Inference respects current column type upper bound

Create a column with a declared broad-but-bounded type, then ensure inference does not produce a type outside the current upper bound.

9. Post-convert(...).with(Infer.None) refinement

Existing scenario can be kept and possibly expanded:

val converted = df.convert(col).with(Infer.None) {
    B(it) as A<Int>
}

converted[col].type() shouldBe typeOf<A<Int>>()
converted.inferType(col)[col].type() shouldBe typeOf<B<Int>>()