expanded on all comments and made all steps of unsupported data source examples clearer and more reproducible

Author: Jolanrensen

examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed/compatibilityLayer.kt

@@ -9,6 +9,7 @@ import org.jetbrains.exposed.v1.core.Table
 import org.jetbrains.exposed.v1.jdbc.Query
 import org.jetbrains.kotlinx.dataframe.AnyFrame
 import org.jetbrains.kotlinx.dataframe.DataFrame
+import org.jetbrains.kotlinx.dataframe.annotations.DataSchema
 import org.jetbrains.kotlinx.dataframe.api.convertTo
 import org.jetbrains.kotlinx.dataframe.api.toDataFrame
 import org.jetbrains.kotlinx.dataframe.codeGen.NameNormalizer
@@ -30,8 +31,9 @@ inline fun <reified T : Any> Iterable<ResultRow>.convertToDataFrame(): DataFrame
     convertToDataFrame().convertTo<T>()
 
 /**
- * Retrieves all columns of any [Iterable][Iterable]`<`[ResultRow][ResultRow]`>`, like [Query][Query],
- * from Exposed row by row and converts the resulting [Map] into a [DataFrame].
+ * Retrieves all columns of an [Iterable][Iterable]`<`[ResultRow][ResultRow]`>` from Exposed, like [Query][Query],
+ * row by row and converts the resulting [Map] of lists into a [DataFrame] by calling
+ * [Map.toDataFrame].
  */
 @JvmName("convertToAnyFrame")
 fun Iterable<ResultRow>.convertToDataFrame(): AnyFrame {
@@ -62,26 +64,44 @@ val Expression<*>.readableName: String
 /**
  * Creates a [DataFrameSchema] from the declared [Table] instance.
  *
+ * This is not needed for conversion, but it can be useful to create a DataFrame [@DataSchema][DataSchema] instance.
+ *
  * @param columnNameToAccessor Optional [MutableMap] which will be filled with entries mapping
  *   the SQL column name to the accessor name from the [Table].
  *   This can be used to define a [NameNormalizer] later.
+ * @see toDataFrameSchemaWithNameNormalizer
  */
 @Suppress("UNCHECKED_CAST")
 fun Table.toDataFrameSchema(columnNameToAccessor: MutableMap<String, String> = mutableMapOf()): DataFrameSchema {
+    // we use reflection to go over all `Column<*>` properties in the Table object
     val columns = this::class.memberProperties
         .filter { it.returnType.isSubtypeOf(typeOf<Column<*>>()) }
         .associate { prop ->
             prop as KProperty1<Table, Column<*>>
 
-            // retrieve the actual column name
+            // retrieve the SQL column name
             val columnName = prop.get(this).name
-            // store the actual column name together with the accessor name in the map
+            // store the SQL column name together with the accessor name in the map
             columnNameToAccessor[columnName] = prop.name
 
             // get the column type from `val a: Column<Type>`
             val type = prop.returnType.arguments.first().type!!
 
+            // and we add the name and column shema type to the `columns` map :)
             columnName to ColumnSchema.Value(type)
         }
     return DataFrameSchemaImpl(columns)
 }
+
+/**
+ * Creates a [DataFrameSchema] from the declared [Table] instance with a [NameNormalizer] to
+ * convert the SQL column names to the corresponding Kotlin property names.
+ *
+ * This is not needed for conversion, but it can be useful to create a DataFrame [@DataSchema][DataSchema] instance.
+ *
+ * @see toDataFrameSchema
+ */
+fun Table.toDataFrameSchemaWithNameNormalizer(): Pair<DataFrameSchema, NameNormalizer> {
+    val columnNameToAccessor = mutableMapOf<String, String>()
+    return Pair(toDataFrameSchema(), NameNormalizer { columnNameToAccessor[it] ?: it })
+}

examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed/main.kt

@@ -58,15 +58,16 @@ fun main() {
 
     // or make plots using Kandy! It's all up to you
 
-    // writing a DataFrame back into an SQL database with Exposed can also be done!
+    // writing a DataFrame back into an SQL database with Exposed can also be done easily!
     transaction(db) {
         addLogger(StdOutSqlLogger)
 
         // first delete the original contents
         Customers.deleteAll()
 
-        // batch insert our rows back into the SQL database
+        // batch-insert our dataframe back into the SQL database as a sequence of rows
         Customers.batchInsert(df.asSequence()) { dfRow ->
+            // we simply go over each value in the row and put it in the right place in the Exposed statement
             for (column in Customers.columns) {
                 this[column as Column<Any?>] = dfRow[column.name]
             }

examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed/tables.kt

@@ -51,8 +51,7 @@ object Customers : Table() {
  * This is what we created the [toDataFrameSchema] function for!
  */
 fun main() {
-    val columnNameToAccessor = mutableMapOf<String, String>()
-    val schema = Customers.toDataFrameSchema(columnNameToAccessor)
+    val (schema, nameNormalizer) = Customers.toDataFrameSchemaWithNameNormalizer()
 
     // checking whether the schema is converted correctly.
     // schema.print()
@@ -62,7 +61,7 @@ fun main() {
     // while keeping the correct column names
     schema.generateDataClasses(
         name = "CustomersDf",
-        nameNormalizer = NameNormalizer { columnNameToAccessor[it] ?: it },
+        nameNormalizer = nameNormalizer,
     ).print()
 }
 

examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/kotlinSpark/typedDataset.kt

@@ -16,24 +16,14 @@ import org.jetbrains.kotlinx.dataframe.api.toDataFrame
 import org.jetbrains.kotlinx.dataframe.api.toList
 import org.jetbrains.kotlinx.spark.api.withSpark
 
-@DataSchema
-data class Name(val firstName: String, val lastName: String)
-
-@DataSchema
-data class Person(
-    val name: Name,
-    val age: Int,
-    val city: String?,
-    val weight: Int?,
-    val isHappy: Boolean,
-)
-
 /**
  * With the Kotlin Spark API, normal Kotlin data classes are supported,
  * meaning we can reuse the same class for Spark and DataFrame!
  *
  * Also, since we use an actual class to define the schema, we need no type conversion!
  *
+ * See [Person] and [Name] for an example.
+ *
  * NOTE: You will likely need to run this function with Java 8 or 11 for it to work correctly.
  * Use the `runKotlinSparkTypedDataset` Gradle task to do so.
  */
@@ -74,3 +64,15 @@ fun main() = withSpark {
     sparkDatasetAgain.printSchema()
     sparkDatasetAgain.show()
 }
+
+@DataSchema
+data class Name(val firstName: String, val lastName: String)
+
+@DataSchema
+data class Person(
+    val name: Name,
+    val age: Int,
+    val city: String?,
+    val weight: Int?,
+    val isHappy: Boolean,
+)