chore: more docs

toolisticon · Sep 22, 2024 · 8259483 · 8259483
1 parent 2f679d5
commit 8259483
Show file tree

Hide file tree

Showing 6 changed files with 29 additions and 3 deletions.
diff --git a/kotlin-code-generation/src/main/kotlin/KotlinCodeGeneration.kt b/kotlin-code-generation/src/main/kotlin/KotlinCodeGeneration.kt
@@ -303,7 +303,6 @@ object KotlinCodeGeneration : KLogging() {
   /**
    * Static access for all builders.
    */
-  @ExperimentalKotlinPoetApi
   @Suppress("ClassName", SUPPRESS_MEMBER_VISIBILITY_CAN_BE_PRIVATE)
   object builder {
     /**

diff --git a/kotlin-code-generation/src/main/kotlin/_types.kt b/kotlin-code-generation/src/main/kotlin/_types.kt
@@ -10,13 +10,26 @@ fun interface Builder<PRODUCT : Any> {
   fun build(): PRODUCT
 }
 
+/**
+ * Builder for PRODUCT that is also a supplier for SPEC, used to combine poetSpec and kcg specs.
+ */
 interface BuilderSupplier<PRODUCT : Any, SPEC : Any> : Builder<PRODUCT>, Supplier<SPEC>
 
+/**
+ * Marks type as className holder.
+ */
 interface WithClassName {
   val className: ClassName
 }
 
+/**
+ * ClassName when used as a file name for fileSpec.
+ */
 typealias FileName = ClassName
+
+/**
+ * The poet string used for formatting.
+ */
 typealias CodeBlockFormat = String
 
 /**

diff --git a/kotlin-code-generation/src/main/kotlin/support/ContextualAnnotation.kt b/kotlin-code-generation/src/main/kotlin/support/ContextualAnnotation.kt
@@ -2,13 +2,17 @@ package io.toolisticon.kotlin.generation.support
 
 import com.squareup.kotlinpoet.ExperimentalKotlinPoetApi
 import io.toolisticon.kotlin.generation.KotlinCodeGeneration
+import io.toolisticon.kotlin.generation.KotlinCodeGeneration.buildAnnotation
 import io.toolisticon.kotlin.generation.spec.KotlinAnnotationSpec
 import io.toolisticon.kotlin.generation.spec.KotlinAnnotationSpecSupplier
 import kotlinx.serialization.Contextual
 
 // TODO: we could also use UseContextualSerialization on the generated file if we collect all classes that require custom serialization in that file.
 
+/**
+ * Builder to create a `@Contextual` annotation.
+ */
 @ExperimentalKotlinPoetApi
 object ContextualAnnotation : KotlinAnnotationSpecSupplier{
-  override fun spec(): KotlinAnnotationSpec = KotlinCodeGeneration.buildAnnotation(Contextual::class)
+  override fun spec(): KotlinAnnotationSpec = buildAnnotation(Contextual::class)
 }
diff --git a/kotlin-code-generation/src/main/kotlin/support/DeprecatedAnnotation.kt b/kotlin-code-generation/src/main/kotlin/support/DeprecatedAnnotation.kt
@@ -2,13 +2,17 @@ package io.toolisticon.kotlin.generation.support
 
 import com.squareup.kotlinpoet.ExperimentalKotlinPoetApi
 import io.toolisticon.kotlin.generation.KotlinCodeGeneration
+import io.toolisticon.kotlin.generation.KotlinCodeGeneration.buildAnnotation
 import io.toolisticon.kotlin.generation.poet.FormatSpecifier.asCodeBlock
 import io.toolisticon.kotlin.generation.spec.KotlinAnnotationSpec
 import io.toolisticon.kotlin.generation.spec.KotlinAnnotationSpecSupplier
 
+/**
+ * Builder to create a `@Deprecated` annotation.
+ */
 @ExperimentalKotlinPoetApi
 data class DeprecatedAnnotation(val message: String, val deprecationLevel: DeprecationLevel? = null) : KotlinAnnotationSpecSupplier {
-  override fun spec(): KotlinAnnotationSpec = KotlinCodeGeneration.buildAnnotation(Deprecated::class) {
+  override fun spec(): KotlinAnnotationSpec = buildAnnotation(Deprecated::class) {
     if (deprecationLevel == null) {
       addMember(message.asCodeBlock())
     } else {

diff --git a/kotlin-code-generation/src/main/kotlin/support/GeneratedAnnotation.kt b/kotlin-code-generation/src/main/kotlin/support/GeneratedAnnotation.kt
@@ -10,6 +10,9 @@ import jakarta.annotation.Generated
 import java.time.Instant
 import kotlin.reflect.KClass
 
+/**
+ * Builder to create a `@Generated` annotation.
+ */
 @ExperimentalKotlinPoetApi
 @Suppress(SUPPRESS_UNUSED)
 data class GeneratedAnnotation(

diff --git a/kotlin-code-generation/src/main/kotlin/support/SuppressAnnotation.kt b/kotlin-code-generation/src/main/kotlin/support/SuppressAnnotation.kt
@@ -7,6 +7,9 @@ import io.toolisticon.kotlin.generation.poet.FormatSpecifier.asCodeBlock
 import io.toolisticon.kotlin.generation.spec.KotlinAnnotationSpec
 import io.toolisticon.kotlin.generation.spec.KotlinAnnotationSpecSupplier
 
+/**
+ * Builder to create a `@Suppress` annotation.
+ */
 @ExperimentalKotlinPoetApi
 data class SuppressAnnotation(val names: List<String> = emptyList()) : KotlinAnnotationSpecSupplier {
   constructor(name: String) : this(listOf(name))