clarifying some docs based on feedback

Author: Jolanrensen

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataColumn.kt

@@ -132,13 +132,18 @@ public interface DataColumn<out T> : BaseColumn<T> {
         /**
          * Creates either a [FrameColumn], [ColumnGroup], or [ValueColumn] by analyzing each value in
          * [values].
+         *
          * This is safer but less efficient than the other functions.
          *
-         * Some conversions are done automatically to attempt to unify the values, like:
-         * - `null` -> [DataFrame.empty][DataFrame.empty]`()` and [DataRow] -> single-row [DataFrame] when there are other
-         *   [DataFrames][DataFrame] present in [values]
-         * - [List][List]`<`[DataRow][DataRow]`<*>>` -> [DataFrame]
-         * etc.
+         * Some conversions are done automatically to attempt to unify the values.
+         *
+         * For instance, when there are other [DataFrames][DataFrame] present in [values], we'll convert:
+         * - `null` -> [DataFrame.empty]`()`
+         * - [DataRow] -> single-row [DataFrame]
+         * - [List][List]`<`[DataRow][DataRow]`<*>>` -> multi-row [DataFrame]
+         *
+         * to be able to create a [FrameColumn].
+         * There are more conversions for other types as well.
          *
          * @param name name of the column
          * @param values the values to represent each row in the column
@@ -163,12 +168,12 @@ public interface DataColumn<out T> : BaseColumn<T> {
          * Calls [createColumnGroup], [createFrameColumn], or [createValueColumn] based on
          * [type].
          *
+         * This may be unsafe but is more efficient than [createWithTypeInference].
+         *
          * Be careful; Values in [values] are NOT checked to adhere to the given [type], nor
-         * do we check whether there are nulls among the values when the given type is [DataFrame]
-         * (a [FrameColumn] cannot contain `null`, this causes runtime exceptions).
-         * When [type] is `DataFrame<*>?`, a [ValueColumn] is created to avoid this issue.
+         * do we check whether there are unexpected nulls among the values.
          *
-         * This may be unsafe but is more efficient than [createWithTypeInference].
+         * It's recommended to use [createValueColumn], [createColumnGroup], and [createFrameColumn] instead.
          *
          * @param name the name of the column
          * @param values the values to represent each row in the column
@@ -181,22 +186,24 @@ public interface DataColumn<out T> : BaseColumn<T> {
             type: KType,
             infer: Infer = Infer.None,
         ): DataColumn<T> =
-            when (type.toColumnKind()) {
+            when (type.toColumnKind()) { // AnyFrame -> Frame, AnyRow? -> Group, else -> Value
                 ColumnKind.Value -> createValueColumn(name, values, type, infer)
+
                 ColumnKind.Group -> createColumnGroup(name, (values as List<AnyRow?>).concat()).asDataColumn().cast()
+
                 ColumnKind.Frame -> createFrameColumn(name, values as List<AnyFrame>).asDataColumn().cast()
             }
 
         /**
          * Calls [createColumnGroup], [createFrameColumn], or [createValueColumn] based on
          * type [T].
          *
-         * Be careful; Values in [values] are NOT checked to adhere to the given [type], nor
-         * do we check whether there are nulls among the values when the given type is [DataFrame]
-         * (a [FrameColumn] cannot contain `null`, this causes runtime exceptions).
-         * When [type] is `DataFrame<*>?`, a [ValueColumn] is created to avoid this issue.
+         * This is generally safe, as [T] can be inferred, and more efficient than [createWithTypeInference].
          *
-         * This may be unsafe but is more efficient than [createWithTypeInference].
+         * Be careful when casting occurs; Values in [values] are NOT checked to adhere to the given/inferred type [T],
+         * nor do we check whether there are unexpected nulls among the values.
+         *
+         * It's recommended to use [createValueColumn], [createColumnGroup], and [createFrameColumn] instead.
          *
          * @param T the (unchecked) common type of [values]
          * @param name the name of the column

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/TypeUtils.kt

@@ -9,6 +9,7 @@ import org.jetbrains.kotlinx.dataframe.DataColumn
 import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.api.Infer
+import org.jetbrains.kotlinx.dataframe.impl.columns.createColumnGuessingType
 import kotlin.reflect.KClass
 import kotlin.reflect.KType
 import kotlin.reflect.KTypeParameter
@@ -385,7 +386,12 @@ internal fun <T> getValuesType(values: List<T>, type: KType, infer: Infer): KTyp
     }
 
 /**
- * Returns the value type of the given [values] sequence.
+ * Returns the guessed value type of the given [values] sequence.
+ *
+ * This function analyzes all [values] once and returns the expected column type.
+ *
+ * The resulting column type may need [values] to be converted to the expected type.
+ * See [createColumnGuessingType] for how to create a column with the guessed type.
  *
  * @param values the values to guess the type from
  * @param upperBound the upper bound of the type to guess

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/constructors.kt

@@ -239,8 +239,8 @@ internal fun <T> createColumnGuessingType(
 
     return when (type.classifier!! as KClass<*>) {
         // guessValueType can only return DataRow if all values are `AnyRow?`
-        // or allColsMakesColGroup == true, all values are `AnyCol`
-        DataRow::class -> {
+        // or allColsMakesColGroup == true, and all values are `AnyCol`
+        DataRow::class ->
             if (allColsMakesColGroup && values.firstOrNull() is AnyCol) {
                 val df = dataFrameOf(values as Iterable<AnyCol>)
                 DataColumn.createColumnGroup(name, df)
@@ -250,7 +250,6 @@ internal fun <T> createColumnGuessingType(
                 }.concat()
                 DataColumn.createColumnGroup(name, df)
             }.asDataColumn().cast()
-        }
 
         DataFrame::class -> {
             val frames = values.map {
@@ -312,7 +311,7 @@ internal fun <T> createColumnGuessingType(
                     // nullable is not given, so we still infer nullability
                     nullable == null && suggestedType is TypeSuggestion.Use -> Infer.Nulls
 
-                    // nullability already inferred by guessValueType
+                    // nullability already handled; inferred by guessValueType or explicitly given
                     else -> Infer.None
                 },
                 defaultValue = defaultValue,