Add Kotlin support for "addGeneratedAnnotation" flag (#1115)

This adds logic so that the Kotlin code generator also supports the
"addGeneratedAnnotation" flag.

Also:
* Add Antora documentation
* Adjust names (generated-annotation -> add-generated-annotation)
* Adjust doc comments

pkl-codegen-kotlin/src/main/kotlin/org/pkl/codegen/kotlin/CliKotlinCodeGeneratorOptions.kt

@@ -38,6 +38,9 @@ data class CliKotlinCodeGeneratorOptions(
   /** Whether generated classes should implement [java.io.Serializable]. */
   val implementSerializable: Boolean = false,
 
+  /** Whether to add the `@Generated` annotation to types */
+  val addGeneratedAnnotation: Boolean = false,
+
   /**
    * A rename mapping for class names.
    *
@@ -57,6 +60,7 @@ data class CliKotlinCodeGeneratorOptions(
       generateKdoc,
       generateSpringBootConfig,
       implementSerializable,
+      addGeneratedAnnotation,
       renames,
     )
 }

pkl-codegen-kotlin/src/main/kotlin/org/pkl/codegen/kotlin/KotlinCodeGenerator.kt

@@ -40,6 +40,9 @@ data class KotlinCodeGeneratorOptions(
   /** Whether to generate classes that implement [java.io.Serializable]. */
   val implementSerializable: Boolean = false,
 
+  /** Whether to add the `@Generated` to generated types. */
+  val addGeneratedAnnotation: Boolean = false,
+
   /**
    * A mapping from Pkl module name prefixes to their replacements.
    *
@@ -455,6 +458,9 @@ class KotlinCodeGenerator(
       if (options.generateSpringBootConfig) {
         generateSpringBootAnnotations(builder)
       }
+      if (options.addGeneratedAnnotation) {
+        builder.addAnnotation(ClassName("org.pkl.config.java", "Generated"))
+      }
 
       builder.primaryConstructor(generateConstructor())
 
@@ -498,6 +504,9 @@ class KotlinCodeGenerator(
       if (options.generateSpringBootConfig) {
         generateSpringBootAnnotations(builder)
       }
+      if (options.addGeneratedAnnotation) {
+        builder.addAnnotation(ClassName("org.pkl.config.java", "Generated"))
+      }
 
       builder.primaryConstructor(generateConstructor())
 

pkl-codegen-kotlin/src/main/kotlin/org/pkl/codegen/kotlin/Main.kt

@@ -79,6 +79,12 @@ class PklKotlinCodegenCommand : ModulesCommand(name = "pkl-codegen-kotlin", help
       )
       .flag()
 
+  private val addGeneratedAnnotation: Boolean by
+    option(
+        names = arrayOf("--add-generated-annotation"),
+        help = "Whether to add a @Generated annotation to the types to be generated.",
+      )
+      .flag()
   private val renames: Map<String, String> by
     option(
         names = arrayOf("--rename"),
@@ -105,6 +111,7 @@ class PklKotlinCodegenCommand : ModulesCommand(name = "pkl-codegen-kotlin", help
         generateKdoc = generateKdoc,
         generateSpringBootConfig = generateSpringboot,
         implementSerializable = implementSerializable,
+        addGeneratedAnnotation = addGeneratedAnnotation,
         renames = renames,
       )
     CliKotlinCodeGenerator(options).run()

pkl-codegen-kotlin/src/test/kotlin/org/pkl/codegen/kotlin/KotlinCodeGeneratorTest.kt

@@ -2029,6 +2029,30 @@ class KotlinCodeGeneratorTest {
     )
   }
 
+  @Test
+  fun `add generated annotation`() {
+    val files =
+      KotlinCodeGeneratorOptions(addGeneratedAnnotation = true)
+        .generateFiles("com.example.MyModule" to "foo: String")
+    assertThat(files).containsKey("kotlin/com/example/MyModule.kt")
+    assertThat(files["kotlin/com/example/MyModule.kt"])
+      .isEqualTo(
+        """
+      package com.example
+
+      import kotlin.String
+      import org.pkl.config.java.Generated
+
+      @Generated
+      data class MyModule(
+        val foo: String
+      )
+
+    """
+          .trimIndent()
+      )
+  }
+
   private fun Map<String, String>.validateContents(
     vararg assertions: kotlin.Pair<String, List<String>>
   ) {