Add KDoc and TODOs for future KDoc

Thijsiez · Nov 16, 2024 · d83fdbb · d83fdbb
1 parent afed50d
commit d83fdbb
Show file tree

Hide file tree

Showing 7 changed files with 197 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -81,12 +81,12 @@ project.afterEvaluate {
   - `eq`, `neq`, `lt`, `gt`, `lte`, `gte`, `in`, `notIn`, `between`, and `notBetween`
 - Supports `like` and `notLike` expressions in a null-safe way for String columns
 - Supports `and` and `or` expressions for building up a query
-- Adds the `PanacheSingleResult<T>` sealed class and `singleResultSafe()` extension function to return a single result without throwing exceptions.
+- Adds the `PanacheSingleResult` sealed class and `singleResultSafe()` extension function to return a single result without throwing exceptions.
   - Allows you to handle no/multiple results with a `when (result) {...}` block instead of try-catching
 ### Code Generation
 - Generate `Column`s for non-transient and non-mapped fields in Panache entities
 - Generate query entry point extension functions for entities with Panache companion objects
-  - `where` to start building a SELECT queries, which can be chained to other Panache functions
+  - `where` to start building a SELECT/DELETE queries, which may be chained to other Panache functions
   - `update` with setters to bulk-update multiple rows at once
   - Single expression `updateAll` to update all rows without requiring a WHERE clause
   - Single expression `count`, `delete`, `find`, `stream`, `single`, `singleSafe`, and `multiple`

diff --git a/src/main/kotlin/ch/icken/processor/ColumnType.kt b/src/main/kotlin/ch/icken/processor/ColumnType.kt
@@ -20,6 +20,16 @@ import kotlin.annotation.AnnotationRetention.SOURCE
 import kotlin.annotation.AnnotationTarget.PROPERTY
 import kotlin.reflect.KClass
 
+/**
+ * Specifies the generic type of the generated [Column][ch.icken.query.Column] to match the type as used by Hibernate.
+ *
+ * The intended use case for this annotation is when the column's Kotlin type is different from your database.
+ * When using JPA's [@Convert][jakarta.persistence.Convert] annotation, Hibernate converts to and from the type as
+ * specified by the [@Converter][jakarta.persistence.Converter]. Panache uses this other type in its queries,
+ * so it needs to be known during [Column][ch.icken.query.Column] generation.
+ *
+ * @property type the generic type to be used by the generated [Column][ch.icken.query.Column]
+ */
 @Retention(SOURCE)
 @Target(PROPERTY)
 annotation class ColumnType(

diff --git a/src/main/kotlin/ch/icken/processor/PanacheCompanionBaseProcessor.kt b/src/main/kotlin/ch/icken/processor/PanacheCompanionBaseProcessor.kt
@@ -86,6 +86,7 @@ class PanacheCompanionBaseProcessor(
         //endregion
 
         //region where, and, or
+        //TODO kdoc
         val where = FunSpec.builder(FUNCTION_NAME_WHERE)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
@@ -95,13 +96,15 @@ class PanacheCompanionBaseProcessor(
                 MemberName(QueryComponentClassName.packageName, FUNCTION_NAME_WHERE), columnsObjectClassName)
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_WHERE$classSimpleName"))
 
+        //TODO kdoc
         val and = FunSpec.builder(FUNCTION_NAME_AND)
             .addModifiers(KModifier.INLINE)
             .receiver(queryComponentType)
             .addParameter(PARAM_NAME_EXPRESSION, expressionParameterLambdaType)
             .returns(queryComponentType)
             .addStatement("return $FUNCTION_NAME_AND($PARAM_NAME_EXPRESSION(%T))", columnsObjectClassName)
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_AND$classSimpleName"))
+        //TODO kdoc
         val or = FunSpec.builder(FUNCTION_NAME_OR)
             .addModifiers(KModifier.INLINE)
             .receiver(queryComponentType)
@@ -112,6 +115,7 @@ class PanacheCompanionBaseProcessor(
         //endregion
 
         //region count, delete, find, stream
+        //TODO kdoc
         val count = FunSpec.builder(FUNCTION_NAME_COUNT)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
@@ -120,6 +124,7 @@ class PanacheCompanionBaseProcessor(
             .addStatement("return $FUNCTION_NAME_WHERE($PARAM_NAME_EXPRESSION).$FUNCTION_NAME_COUNT()")
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_COUNT$classSimpleName"))
 
+        //TODO kdoc
         val delete = FunSpec.builder(FUNCTION_NAME_DELETE)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
@@ -129,13 +134,15 @@ class PanacheCompanionBaseProcessor(
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_DELETE$classSimpleName"))
 
         val findReturns = PanacheQueryClassName.plusParameter(className)
+        //TODO kdoc
         val find = FunSpec.builder(FUNCTION_NAME_FIND)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
             .addParameter(PARAM_NAME_EXPRESSION, expressionParameterLambdaType)
             .returns(findReturns)
             .addStatement("return $FUNCTION_NAME_WHERE($PARAM_NAME_EXPRESSION).$FUNCTION_NAME_FIND()")
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_FIND$classSimpleName"))
+        //TODO kdoc
         val findSorted = FunSpec.builder(FUNCTION_NAME_FIND)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
@@ -146,13 +153,15 @@ class PanacheCompanionBaseProcessor(
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_FIND_SORTED$classSimpleName"))
 
         val streamReturns = StreamClassName.plusParameter(className)
+        //TODO kdoc
         val stream = FunSpec.builder(FUNCTION_NAME_STREAM)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
             .addParameter(PARAM_NAME_EXPRESSION, expressionParameterLambdaType)
             .returns(streamReturns)
             .addStatement("return $FUNCTION_NAME_WHERE($PARAM_NAME_EXPRESSION).$FUNCTION_NAME_STREAM()")
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_STREAM$classSimpleName"))
+        //TODO kdoc
         val streamSorted = FunSpec.builder(FUNCTION_NAME_STREAM)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
@@ -164,13 +173,15 @@ class PanacheCompanionBaseProcessor(
         //endregion
 
         //region single, multiple
+        //TODO kdoc
         val single = FunSpec.builder(FUNCTION_NAME_SINGLE)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
             .addParameter(PARAM_NAME_EXPRESSION, expressionParameterLambdaType)
             .returns(className)
             .addStatement("return $FUNCTION_NAME_WHERE($PARAM_NAME_EXPRESSION).single()")
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_SINGLE$classSimpleName"))
+        //TODO kdoc
         val singleSafe = FunSpec.builder(FUNCTION_NAME_SINGLE_SAFE)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
@@ -180,13 +191,15 @@ class PanacheCompanionBaseProcessor(
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_SINGLE_SAFE$classSimpleName"))
 
         val multipleReturns = ListClassName.plusParameter(className)
+        //TODO kdoc
         val multiple = FunSpec.builder(FUNCTION_NAME_MULTIPLE)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
             .addParameter(PARAM_NAME_EXPRESSION, expressionParameterLambdaType)
             .returns(multipleReturns)
             .addStatement("return $FUNCTION_NAME_WHERE($PARAM_NAME_EXPRESSION).multiple()")
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_MULTIPLE$classSimpleName"))
+        //TODO kdoc
         val multipleSorted = FunSpec.builder(FUNCTION_NAME_MULTIPLE)
             .addModifiers(KModifier.INLINE)
             .receiver(companionClassName)
@@ -199,26 +212,30 @@ class PanacheCompanionBaseProcessor(
 
         //region update, updateAll
         val updateExtensionFunction = MemberName(InitialUpdateComponentClassName.packageName, FUNCTION_NAME_UPDATE)
+        //TODO kdoc
         val update = FunSpec.builder(FUNCTION_NAME_UPDATE)
             .receiver(companionClassName)
             .addParameter(PARAM_NAME_SETTER, setterExpressionParameterLambdaType)
             .returns(initialUpdateComponentType)
             .addStatement("return %M(%T, $PARAM_NAME_SETTER)", updateExtensionFunction, columnsObjectClassName)
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_UPDATE$classSimpleName"))
+        //TODO kdoc
         val updateMultiple = FunSpec.builder(FUNCTION_NAME_UPDATE)
             .receiver(companionClassName)
             .addParameter(PARAM_NAME_SETTERS, setterExpressionParameterLambdaType, KModifier.VARARG)
             .returns(initialUpdateComponentType)
             .addStatement("return %M(%T, $PARAM_NAME_SETTERS)", updateExtensionFunction, columnsObjectClassName)
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_UPDATE_MULTIPLE$classSimpleName"))
 
+        //TODO kdoc
         val updateAll = FunSpec.builder(FUNCTION_NAME_UPDATE_ALL)
             .receiver(companionClassName)
             .addParameter(PARAM_NAME_SETTER, setterExpressionParameterLambdaType)
             .returns(IntClassName)
             .addStatement("return %M(%T, $PARAM_NAME_SETTER).executeWithoutWhere()",
                 updateExtensionFunction, columnsObjectClassName)
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_UPDATE_ALL$classSimpleName"))
+        //TODO kdoc
         val updateAllMultiple = FunSpec.builder(FUNCTION_NAME_UPDATE_ALL)
             .receiver(companionClassName)
             .addParameter(PARAM_NAME_SETTERS, setterExpressionParameterLambdaType, KModifier.VARARG)
@@ -229,6 +246,7 @@ class PanacheCompanionBaseProcessor(
         //endregion
 
         //region whereUpdate, andUpdate, orUpdate
+        //TODO kdoc
         val whereUpdate = FunSpec.builder(FUNCTION_NAME_WHERE)
             .addModifiers(KModifier.INLINE)
             .receiver(initialUpdateComponentType)
@@ -237,13 +255,15 @@ class PanacheCompanionBaseProcessor(
             .addStatement("return $FUNCTION_NAME_WHERE($PARAM_NAME_EXPRESSION(%T))", columnsObjectClassName)
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_WHERE_UPDATE$classSimpleName"))
 
+        //TODO kdoc
         val andUpdate = FunSpec.builder(FUNCTION_NAME_AND)
             .addModifiers(KModifier.INLINE)
             .receiver(logicalUpdateComponentType)
             .addParameter(PARAM_NAME_EXPRESSION, expressionParameterLambdaType)
             .returns(logicalUpdateComponentType)
             .addStatement("return $FUNCTION_NAME_AND($PARAM_NAME_EXPRESSION(%T))", columnsObjectClassName)
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_AND_UPDATE$classSimpleName"))
+        //TODO kdoc
         val orUpdate = FunSpec.builder(FUNCTION_NAME_OR)
             .addModifiers(KModifier.INLINE)
             .receiver(logicalUpdateComponentType)
@@ -254,13 +274,15 @@ class PanacheCompanionBaseProcessor(
         //endregion
 
         //region andExpression, orExpression
+        //TODO kdoc
         val andExpression = FunSpec.builder(FUNCTION_NAME_AND)
             .addModifiers(KModifier.INLINE)
             .receiver(expressionType)
             .addParameter(PARAM_NAME_EXPRESSION, expressionParameterLambdaType)
             .returns(expressionType)
             .addStatement("return $FUNCTION_NAME_AND($PARAM_NAME_EXPRESSION(%T))", columnsObjectClassName)
             .addAnnotation(jvmNameAnnotation("$FUNCTION_NAME_AND_EXPRESSION$classSimpleName"))
+        //TODO kdoc
         val orExpression = FunSpec.builder(FUNCTION_NAME_OR)
             .addModifiers(KModifier.INLINE)
             .receiver(expressionType)