updates convert and convertTo docs with new char parser behavior and generally a better explanation of how convertTo works

Author: Jolanrensen

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt

@@ -3,6 +3,7 @@
 package org.jetbrains.kotlinx.dataframe.samples.api
 
 import io.kotest.matchers.shouldBe
+import org.jetbrains.kotlinx.dataframe.AnyFrame
 import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.alsoDebug
@@ -1102,11 +1103,17 @@ class Modify : TestBase() {
     @TransformDataFrameExpressions
     fun customConverters() {
         // SampleStart
-        val df = dataFrameOf("a", "b")(1, "2")
+        val df: AnyFrame = dataFrameOf(
+            "a" to columnOf(1, 2, 3),
+            "b" to columnOf("1", "2", "3"),
+        )
         df.convertTo<MySchema> {
-            convert<Int>().with { MyType(it) } // converts `a` from Int to MyType
-            parser { MyType(it.toInt()) } // converts `b` from String to MyType
-            fill { c }.with { a.value + b.value } // computes missing column `c`
+            // providing the converter: Int -> MyType, so column `a` can be converted
+            convert<Int>().with { MyType(it) }
+            // providing the parser: String -> MyType, so column `b` can be converted
+            parser { MyType(it.toInt()) }
+            // providing the filler for `c`, as it's missing in `df`
+            fill { c }.with { a.value + b.value }
         }
         // SampleEnd
     }

docs/StardustDocs/topics/convert.md

@@ -56,7 +56,7 @@ df.convert { name }.asColumn { col ->
 <!---END-->
 
 
-`convert` supports automatic type conversions between the following types:
+`convert {}.to<>()` supports automatic type conversions between the following types:
 * `String`, `Char` (uses [`parse`](parse.md) to convert from `String` to other types)
 * `Boolean`
 * `Byte`
@@ -71,6 +71,7 @@ df.convert { name }.asColumn { col ->
 * `LocalDate` (kotlinx.datetime and java.time)
 * `LocalTime` (kotlinx.datetime and java.time)
 * `Instant` (kotlinx.datetime, kotlin.time, and java.time)
+* `enum` classes (by name)
 
 Note that converting between `Char` and `Int` is done by ASCII character code.
 This means the `Char` `'1'` becomes the `Int` `49`.

docs/StardustDocs/topics/convertTo.md

@@ -1,18 +1,31 @@
 [//]: # (title: convertTo)
 <!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->
 
-[Converts](convert.md) columns in [`DataFrame`](DataFrame.md) to match a given schema [`Schema`](schema.md).
+[Converts](convert.md) all columns in the [`DataFrame`](DataFrame.md) to match a given schema [`Schema`](schema.md).
 
 ```kotlin
 convertTo<Schema>(excessiveColumns = ExcessiveColumns.Keep)
 ```
 
-**Related operations**: [](adjustSchema.md)
+**Related operations**: [](adjustSchema.md), [](convert.md)
+
+Conversion to match the target schema is done mostly automatically;
+DataFrame knows how to convert between many types (see [](convert.md) for details and the supported types).
+
+However, if you have a custom type in your target schema, or the automatic conversion fails,
+you can provide a custom converter, parser, or filler for it.
+These have priority over the automatic ones.
 
 Customization DSL:
-* `convert`—how specific column types should be converted
-* `parser`—how to parse strings into custom types
-* `fill`—how to fill missing columns
+* `convert<A>.with { it.toB() }`
+  * Provides `convertTo<>()` with the knowledge of how to convert `A` to `B`
+* `parser { YourType.fromString(it) }`
+  * Provides `convertTo<>()` with the knowledge of how to parse strings/chars into `YourType`
+  * Shortcut for `convert<String>().with { YourType.fromString(it) }`
+  * Chars are treated as strings unless you explicitly specify `convert<Char>().with { YourType.fromChar(it) }`
+* `fill { some cols }.with { rowExpression }`
+  * Makes `convertTo<>()` fill missing (or existing) columns from the target schema 
+    with values computed by the given row expression
 
 <!---FUN customConvertersData-->
 
@@ -27,11 +40,17 @@ class MySchema(val a: MyType, val b: MyType, val c: Int)
 <!---FUN customConverters-->
 
 ```kotlin
-val df = dataFrameOf("a", "b")(1, "2")
+val df: AnyFrame = dataFrameOf(
+    "a" to columnOf(1, 2, 3),
+    "b" to columnOf("1", "2", "3"),
+)
 df.convertTo<MySchema> {
-    convert<Int>().with { MyType(it) } // converts `a` from Int to MyType
-    parser { MyType(it.toInt()) } // converts `b` from String to MyType
-    fill { c }.with { a.value + b.value } // computes missing column `c`
+    // providing the converter: Int -> MyType, so column `a` can be converted
+    convert<Int>().with { MyType(it) }
+    // providing the parser: String -> MyType, so column `b` can be converted
+    parser { MyType(it.toInt()) }
+    // providing the filler for `c`, as it's missing in `df`
+    fill { c }.with { a.value + b.value }
 }
 ```