Skip to content

Commit ec8901f

Browse files
JolanrensenJolanrensen
committed
Writing kdocs for generateCode
1 parent b8e90f8 commit ec8901f

File tree

4 files changed

+159
-7
lines changed

4 files changed

+159
-7
lines changed

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

Lines changed: 148 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,89 @@
11
package org.jetbrains.kotlinx.dataframe.api
22

33
import org.jetbrains.kotlinx.dataframe.DataFrame
4+
import org.jetbrains.kotlinx.dataframe.annotations.ColumnName
5+
import org.jetbrains.kotlinx.dataframe.annotations.DataSchema
46
import org.jetbrains.kotlinx.dataframe.codeGen.CodeGenerator
57
import org.jetbrains.kotlinx.dataframe.codeGen.MarkerVisibility
68
import org.jetbrains.kotlinx.dataframe.codeGen.NameNormalizer
9+
import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
10+
import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
11+
import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls
12+
import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
713
import org.jetbrains.kotlinx.dataframe.impl.codeGen.from
814
import org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema
915

16+
// region Docs
17+
18+
/**
19+
* Generates a [CodeString] containing generated [@DataSchema][DataSchema] $[TYPES]
20+
* for the given $[RECEIVER]
21+
* (including all nested [frame columns][FrameColumn] and [column groups][ColumnGroup]).
22+
*
23+
* These generated declarations can also be called "markers".
24+
*
25+
* This is useful when working with the compiler plugin in cases where the schema
26+
* cannot be inferred automatically from the source.
27+
*
28+
* This function is a simplified wrapper for the more advanced and customizable
29+
* [CodeGenerator] API.
30+
* For more customizability, have a look at [CodeGenerator.create()][CodeGenerator.create].
31+
*
32+
* For more information: {@include [DocumentationUrls.DataSchemaGeneration]}
33+
*
34+
* @return [CodeString] – A value class wrapper for [String], containing
35+
* the generated Kotlin code of data schema declarations (markers).
36+
*/
37+
@ExcludeFromSources
38+
private interface CommonGenerateCodeDocs {
39+
40+
// "interfaces" or "data classes"
41+
interface TYPES
42+
43+
// "DataFrameSchema" or "DataFrame"
44+
interface RECEIVER
45+
}
46+
47+
@ExcludeFromSources
48+
private interface Params {
49+
50+
/** @param markerName The base name to use for generated data schema declarations (markers). */
51+
interface MarkerName
52+
53+
/** @include [MarkerName] If not specified, generates a name from type [T]. */
54+
interface MarkerNameOptional
55+
56+
/** @param fields Whether to generate fields (`val ...:`) inside the generated data schema declarations (markers). */
57+
interface Fields
58+
59+
/** @param extensionProperties Whether to generate extension properties in addition to data schema declarations (markers). */
60+
interface ExtensionProperties
61+
62+
/** @param visibility Visibility modifier for the generated declarations (markers). */
63+
interface Visibility
64+
65+
/** @param useFqNames If `true`, fully qualified type names will be used in generated code. */
66+
interface UseFqNames
67+
68+
/**
69+
* @param nameNormalizer Strategy for converting column names (with spaces, underscores, etc.) to valid Kotlin identifiers.
70+
* Columns will keep their original name inside the dataframe via [@ColumnName][ColumnName].
71+
*/
72+
interface NameNormalizer
73+
}
74+
75+
// endregion
76+
1077
// region DataFrame
1178

79+
/**
80+
* @include [CommonGenerateCodeDocs]
81+
* {@set [CommonGenerateCodeDocs.RECEIVER] [DataFrame's][this] [schema][DataFrameSchema]}
82+
* {@set [CommonGenerateCodeDocs.TYPES] interfaces and extension properties}
83+
*
84+
* @include [Params.Fields] Default is `true`.
85+
* @include [Params.ExtensionProperties] Default is `true`.
86+
*/
1287
public inline fun <reified T> DataFrame<T>.generateCode(
1388
fields: Boolean = true,
1489
extensionProperties: Boolean = true,
@@ -19,6 +94,16 @@ public inline fun <reified T> DataFrame<T>.generateCode(
1994
extensionProperties = extensionProperties,
2095
)
2196

97+
/**
98+
* @include [CommonGenerateCodeDocs]
99+
* {@set [CommonGenerateCodeDocs.RECEIVER] [DataFrame's][this] [schema][DataFrameSchema]}
100+
* {@set [CommonGenerateCodeDocs.TYPES] interfaces and extension properties}
101+
*
102+
* @include [Params.MarkerName]
103+
* @include [Params.Fields] Default is `true`.
104+
* @include [Params.ExtensionProperties] Default is `true`.
105+
* @include [Params.Visibility] Default is [MarkerVisibility.IMPLICIT_PUBLIC].
106+
*/
22107
public fun <T> DataFrame<T>.generateCode(
23108
markerName: String,
24109
fields: Boolean = true,
@@ -32,11 +117,39 @@ public fun <T> DataFrame<T>.generateCode(
32117
visibility = visibility,
33118
)
34119

120+
/**
121+
* @include [CommonGenerateCodeDocs]
122+
* {@set [CommonGenerateCodeDocs.RECEIVER] [DataFrame's][this] [schema][DataFrameSchema]}
123+
* {@set [CommonGenerateCodeDocs.TYPES] interfaces}
124+
*
125+
* @include [Params.MarkerNameOptional]
126+
*/
35127
public inline fun <reified T> DataFrame<T>.generateInterfaces(): CodeString =
36128
schema().generateInterfaces(
37129
markerName = markerName<T>(),
38130
)
39131

132+
/**
133+
* @include [CommonGenerateCodeDocs]
134+
* {@set [CommonGenerateCodeDocs.RECEIVER] [DataFrame's][this] [schema][DataFrameSchema]}
135+
* {@set [CommonGenerateCodeDocs.TYPES] interfaces}
136+
*
137+
* @include [Params.MarkerNameOptional]
138+
*/
139+
public fun <T> DataFrame<T>.generateInterfaces(markerName: String): CodeString =
140+
schema().generateInterfaces(markerName = markerName)
141+
142+
/**
143+
* @include [CommonGenerateCodeDocs]
144+
* {@set [CommonGenerateCodeDocs.RECEIVER] [DataFrame's][this] [schema][DataFrameSchema]}
145+
* {@set [CommonGenerateCodeDocs.TYPES] data classes}
146+
*
147+
* @include [Params.MarkerNameOptional]
148+
* @include [Params.ExtensionProperties] Default is `false`.
149+
* @include [Params.Visibility] Default is [MarkerVisibility.IMPLICIT_PUBLIC].
150+
* @include [Params.UseFqNames] Default is `false`.
151+
* @include [Params.NameNormalizer] Default is [NameNormalizer.default][NameNormalizer.Companion.default].
152+
*/
40153
public inline fun <reified T> DataFrame<T>.generateDataClasses(
41154
markerName: String? = null,
42155
extensionProperties: Boolean = false,
@@ -45,20 +158,27 @@ public inline fun <reified T> DataFrame<T>.generateDataClasses(
45158
nameNormalizer: NameNormalizer = NameNormalizer.default,
46159
): CodeString =
47160
schema().generateDataClasses(
48-
name = markerName ?: markerName<T>(),
161+
markerName = markerName ?: markerName<T>(),
49162
extensionProperties = extensionProperties,
50163
visibility = visibility,
51164
useFqNames = useFqNames,
52165
nameNormalizer = nameNormalizer,
53166
)
54167

55-
public fun <T> DataFrame<T>.generateInterfaces(markerName: String): CodeString =
56-
schema().generateInterfaces(markerName = markerName)
57-
58168
// endregion
59169

60170
// region DataFrameSchema
61171

172+
/**
173+
* @include [CommonGenerateCodeDocs]
174+
* {@set [CommonGenerateCodeDocs.RECEIVER] [DataFrameSchema][this]}
175+
* {@set [CommonGenerateCodeDocs.TYPES] interfaces and extension properties}
176+
*
177+
* @include [Params.MarkerName]
178+
* @include [Params.Fields] Default is `true`.
179+
* @include [Params.ExtensionProperties] Default is `true`.
180+
* @include [Params.Visibility] Default is [MarkerVisibility.IMPLICIT_PUBLIC].
181+
*/
62182
@JvmName("generateCodeForSchema")
63183
public fun DataFrameSchema.generateCode(
64184
markerName: String,
@@ -77,6 +197,13 @@ public fun DataFrameSchema.generateCode(
77197
).code.declarations.toCodeString()
78198
}
79199

200+
/**
201+
* @include [CommonGenerateCodeDocs]
202+
* {@set [CommonGenerateCodeDocs.RECEIVER] [DataFrameSchema][this]}
203+
* {@set [CommonGenerateCodeDocs.TYPES] interfaces}
204+
*
205+
* @include [Params.MarkerName]
206+
*/
80207
@JvmName("generateInterfacesForSchema")
81208
public fun DataFrameSchema.generateInterfaces(markerName: String): CodeString =
82209
generateCode(
@@ -85,9 +212,20 @@ public fun DataFrameSchema.generateInterfaces(markerName: String): CodeString =
85212
extensionProperties = false,
86213
)
87214

215+
/**
216+
* @include [CommonGenerateCodeDocs]
217+
* {@set [CommonGenerateCodeDocs.RECEIVER] [DataFrameSchema][this]}
218+
* {@set [CommonGenerateCodeDocs.TYPES] data classes}
219+
*
220+
* @include [Params.MarkerName]
221+
* @include [Params.ExtensionProperties] Default is `false`.
222+
* @include [Params.Visibility] Default is [MarkerVisibility.IMPLICIT_PUBLIC].
223+
* @include [Params.UseFqNames] Default is `false`.
224+
* @include [Params.NameNormalizer] Default is [NameNormalizer.default][NameNormalizer.Companion.default].
225+
*/
88226
@JvmName("generateDataClassesForSchema")
89227
public fun DataFrameSchema.generateDataClasses(
90-
name: String,
228+
markerName: String,
91229
extensionProperties: Boolean = false,
92230
visibility: MarkerVisibility = MarkerVisibility.IMPLICIT_PUBLIC,
93231
useFqNames: Boolean = false,
@@ -96,7 +234,7 @@ public fun DataFrameSchema.generateDataClasses(
96234
val codeGen = CodeGenerator.create(useFqNames)
97235
return codeGen.generate(
98236
schema = this,
99-
name = name,
237+
name = markerName,
100238
fields = true,
101239
extensionProperties = extensionProperties,
102240
isOpen = false,
@@ -121,6 +259,10 @@ internal inline fun <reified T> markerName(): String =
121259
*/
122260
public val NameNormalizer.Companion.default: NameNormalizer get() = NameNormalizer.from(setOf('\t', ' ', '_'))
123261

262+
/**
263+
* A value class wrapper for [String], containing
264+
* generated Kotlin code of data schema declarations (markers) and optionally extension properties.
265+
*/
124266
@JvmInline
125267
public value class CodeString(public val value: String) {
126268
override fun toString(): String = value

‎core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/codeGen/Marker.kt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ import org.jetbrains.kotlinx.dataframe.impl.schema.DataFrameSchemaImpl
44
import org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema
55
import kotlin.reflect.KClass
66

7+
/**
8+
* Which type of visibility the marker (generated class-like code declaration)
9+
* will have:
10+
* - [INTERNAL][INTERNAL]: "internal"
11+
* - [IMPLICIT_PUBLIC][IMPLICIT_PUBLIC]: ""
12+
* - [EXPLICIT_PUBLIC][EXPLICIT_PUBLIC]: "public"
13+
*/
714
public enum class MarkerVisibility {
815
INTERNAL,
916
IMPLICIT_PUBLIC,

‎core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,4 +116,7 @@ internal interface DocumentationUrls {
116116

117117
/** [See `explode` on the documentation website.]({@include [Url]}/explode.html) */
118118
interface Explode
119+
120+
/** [See `Data Schemas/Data Classes Generation` on the documentation website.]({@include [Url]}/dataschema-data-classes-generation.html) */
121+
interface DataSchemaGeneration
119122
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ fun main() {
5959
// we use a NameNormalizer to let DataFrame generate the same accessors as in the Table
6060
// while keeping the correct column names
6161
schema.generateDataClasses(
62-
name = "DfCustomers",
62+
markerName = "DfCustomers",
6363
nameNormalizer = nameNormalizer,
6464
).print()
6565
}

0 commit comments

Comments
 (0)