Update docs for convertTo

Author: nikitinas

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convertTo.kt

@@ -16,7 +16,25 @@ import kotlin.reflect.KProperty
 import kotlin.reflect.KType
 import kotlin.reflect.typeOf
 
-public enum class ExcessiveColumns { Remove, Keep, Fail }
+/**
+ * Specifies how to handle columns in original dataframe that were not mathced to any column in destination dataframe schema.
+ */
+public enum class ExcessiveColumns {
+    /**
+     * Remove excessive columns from resulting dataframe
+     */
+    Remove,
+
+    /**
+     * Keep excessive columns in resulting dataframe
+     */
+    Keep,
+
+    /**
+     * Throw [ExcessiveColumnsException] if any excessive columns were found in the original dataframe
+     */
+    Fail
+}
 
 /**
  * Holds data context for [fill] operation

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

@@ -926,14 +926,16 @@ class Modify : TestBase() {
     @Test
     fun customConverters() {
         // SampleStart
-        class IntClass(val value: Int)
+        class MyType(val value: Int)
 
         @DataSchema
-        class IntSchema(val ints: IntClass)
+        class MySchema(val a: MyType, val b: MyType, val c: Int)
 
-        val df = dataFrameOf("ints")(1, 2, 3)
-        df.convertTo<IntSchema> {
-            convert<Int>().with { IntClass(it) }
+        val df = dataFrameOf("a", "b")(1, "2")
+        df.convertTo<MySchema> {
+            convert<Int>().with { MyType(it) } // used to convert `a` from Int to MyType
+            parser { MyType(it.toInt()) } // used to convert `b` from String to MyType
+            fill { c }.with { a.value + b.value } // used to compute missing column `c`
         }
         // SampleEnd
     }

docs/StardustDocs/topics/convertTo.md

@@ -1,26 +1,29 @@
 [//]: # (title: convertTo)
 <!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->
 
-[Converts](convert.md) columns in `DataFrame` to match given schema.
+[Converts](convert.md) columns in `DataFrame` to match given schema `Schema`
 
 ```kotlin
-convertTo<T>()
+convertTo<Schema>(excessiveColumns = ExcessiveColumns.Keep)
 ```
 
-Any additional columns will be dropped.
-
-You can provide custom converters and parsers:
+Customization DSL:
+* `convert` - how specific column types should be converted
+* `parser` - how to parse strings into custom types
+* `fill` - how to fill missing columns
 <!---FUN customConverters-->
 
 ```kotlin
-class IntClass(val value: Int)
+class MyType(val value: Int)
 
 @DataSchema
-class IntSchema(val ints: IntClass)
+class MySchema(val a: MyType, val b: MyType, val c: Int)
 
-val df = dataFrameOf("ints")(1, 2, 3)
-df.convertTo<IntSchema> {
-    convert<Int>().with { IntClass(it) }
+val df = dataFrameOf("a", "b")(1, "2")
+df.convertTo<MySchema> {
+    convert<Int>().with { MyType(it) } // used to convert `a` from Int to MyType
+    parser { MyType(it.toInt()) } // used to convert `b` from String to MyType
+    fill { c }.with { a.value + b.value } // used to compute missing column `c`
 }
 ```