verify DataSchema kdoc examples and update with more information

Author: koperagen

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/annotations/DataSchema.kt

@@ -5,15 +5,15 @@ import org.jetbrains.kotlinx.dataframe.api.convertTo
 
 /**
  * This annotation marks an interface or data class as a [data schema](https://kotlin.github.io/dataframe/schemas.html).
+ * An annotated declaration should be a non-local and non-private interface or class.
  *
  * This annotation generates an extension properties API for a declaration according to its properties.
- * An annotated declaration should be a non-local and non-private interface or class.
- * The aim is to provide a convenient syntax for working with a dataframe instance right after reading it from CSV,
+ * The aim is to provide a convenient class-like syntax for working with a dataframe instance after reading it from CSV,
  * JSON, databases, Arrow, or other sources.
  *
  * After a `val df = DataFrame.read*` operation, `df` is the source of truth for the data schema.
  * One way to look at it is that a data schema tells the compiler what is already there; it does not affect reading.
- * See the related operations in the See also section.
+ *
  * Given the initial schema of the data you read, the
  * [compiler plugin](https://github.com/JetBrains/kotlin/tree/master/plugins/kotlin-dataframe) provides a typed result
  * for most operations.
@@ -44,15 +44,28 @@ import org.jetbrains.kotlinx.dataframe.api.convertTo
  *     val df = DataFrame.readJson(url).cast<Group>()
  *     val groupId: String = df.id[0] // Properties-style access to columns and values.
  *
- *     val df1 = df.asGroupBy { participants }.aggregate {
- *         count() into "groupSize"
- *         distinct { city } into "cities"
- *     }
+ *    val df1 = df.asGroupBy { participants }.aggregate {
+ *        count() into "groupSize"
+ *        city.distinct().toList() into "cities"
+ *    }
  *
- *     // The compiler plugin uses prior knowledge of `Group` and the aggregate operation to infer new columns.
- *     val cities: List<String> = df1.cities[0]
+ *    // The compiler plugin uses prior knowledge of `Group` and the aggregate operation to infer new columns.
+ *    val cities: List<String?> = df1.cities[0]
  * }
  * ```
+ * Schema properties describe the corresponding dataframe columns:
+ *
+ * - A property of a regular type `V` corresponds to a `DataColumn<V>`.
+ * - A property of type `T`, where `T` is annotated with `@DataSchema`, corresponds to a `ColumnGroup<T>`.
+ * - A property of type `List<T>`, where `T` is annotated with `@DataSchema`, corresponds to a `FrameColumn<T>`.
+ *
+ * After casting a dataframe to `DataFrame<Group>`, it can be converted to data-class instances:
+ * ```kotlin
+ * val url = "https://raw.githubusercontent.com/Kotlin/dataframe/refs/heads/master/data/participants.json"
+ * val df = DataFrame.readJson(url).cast<Group>()
+ * val groups: List<Group> = df.toList()
+ * val participants: List<Person> = groups.first().participants
+ * ```
  *
  * @see [org.jetbrains.kotlinx.dataframe.api.generateDataClasses]
  * @see [org.jetbrains.kotlinx.dataframe.api.generateInterfaces]