Added kdocs for DataSchema and DataRowSchema#1775
Conversation
koperagen
force-pushed
the
dataschema-documentation
branch
from
3d9c104 to
7ab74cf
Compare
| * Given the initial schema of the data you read, the compiler plugin will provide a typed result for most operations. | ||
| * | ||
| * Example: | ||
| * ``` |
There was a problem hiding this comment.
please annotate any code samples with the right file format to get highlights, anywhere you use Markdown ;P
| * @DataSchema | ||
| * data class Group( | ||
| * val id: String, | ||
| * val participants: List<Person> |
There was a problem hiding this comment.
inconsistent trailing commas
| * ) | ||
| * | ||
| * fun main() { | ||
| * val url = "https://raw.githubusercontent.com/Kotlin/dataframe/refs/heads/master/data/participants.json" |
There was a problem hiding this comment.
inconsistent spacing. I might recommend using the @sample KoDEx tag :) similar to Korro, we can include code between // SampleStart and // SampleEnd comments, making sure it compiles and is formatted correctly.
| import org.jetbrains.kotlinx.dataframe.api.cast | ||
| import org.jetbrains.kotlinx.dataframe.api.convertTo | ||
|
|
||
| /** |
There was a problem hiding this comment.
I'd start a bit more generally and introductorily before jumping into exactly what it does.
So: "This annotation marks an interface or data class as 'data schema'" (link to https://kotlin.github.io/dataframe/schemas.html). Then continue with "It's used to generate extension properties, etc.". Gives a bit more context to this key DataFrame component :)
|
|
||
| /** | ||
| * Annotation to generate extension properties API for a given declaration, according to its properties. | ||
| * Annotated declaration should be non-local and non-private interface or a class. |
There was a problem hiding this comment.
*Annotated declaration should be a non-local and non-private interface or class.
| /** | ||
| * Annotation to generate extension properties API for a given declaration, according to its properties. | ||
| * Annotated declaration should be non-local and non-private interface or a class. | ||
| * The aim here is to provide convenient syntax for working with a dataframe instance right after reading from it CSV, JSON, Databases, Arrow, etc. |
| * fun main() { | ||
| * val url = "https://raw.githubusercontent.com/Kotlin/dataframe/refs/heads/master/data/participants.json" | ||
| * val df = DataFrame.readJson(url).cast<Group>() | ||
| * val i: Int = df.id[0] // properties style access to columns and values |
There was a problem hiding this comment.
you can come up with a better name than i and l right? ;P I know it's not relevant to the example itself, but I feel we should still set a good example with expressive variable names.
| * distinct { city } into "cities" | ||
| * } | ||
| * | ||
| * // now compiler plugin uses previous knowledge of `Group` combined with its understanding of aggregate operation |
| * @see [org.jetbrains.kotlinx.dataframe.DataFrame.convertTo] | ||
| */ | ||
| @Target(AnnotationTarget.CLASS) | ||
| public annotation class DataSchema(val isOpen: Boolean = true) |
There was a problem hiding this comment.
We should probably explain what isOpen does
| import org.jetbrains.kotlinx.dataframe.annotations.DataSchema | ||
|
|
||
| /** | ||
| * Marker interface that's automatically added to classes annotated with [DataSchema] |
There was a problem hiding this comment.
... why? (because it can help with .append() etc.) Also, we should specify how this is added (with the compiler plugin) and that it's added only to data classes, not to interfaces (right?) and why.
"Added" -> "Added as supertype"
| * data class Person(val name: String, val age: Int) | ||
| * | ||
| * fun main() { | ||
| * val df = dataFrameOf(Person("Alice", 30), Person("Bob", 25)) |
There was a problem hiding this comment.
single space indent ;P Same story, try @sample :) You could even @sample a piece of code and exclude that from sources in this file. For instance:
@ExcludeFromSources
private interface Sample {
// to make it compile without the compiler plugin
fun <T> dataFrameOf(vararg rows: T): DataFrame<T> = TODO()
// SampleStart
@DataSchema
data class Person(val name: String, val age: Int)
fun main() {
val df: DataFrame<Person> = dataFrameOf(Person("Alice", 30), Person("Bob", 25))
}
// SampleEnd
}
/**
* Example:
* @sample [Sample]
*/
public inline fun <reified T : DataRowSchema> dataFrameOf(vararg rows: T): DataFrame<T> =
rows.asIterable().toDataFrame()There was a problem hiding this comment.
append could also do with a small sample like this :)
|
Useful! :) Overall I like the extra information, but I feel it lacks some links to other resources. We have a plethora of information on the website we should link to |
2 participants
I tried to fill in the gap and at the same time provide a new perspective, my Nth attempt to explain dataschema :))