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

docs/modules/java-binding/partials/cli-codegen-options.adoc

@@ -29,6 +29,13 @@ Default: (not set) +
 Flag that indicates to generate classes that implement `java.io.Serializable`.
 ====
 
+.--add-generated-annotation
+[%collapsible]
+====
+Default: (not set) +
+Flag that indicates to add the `org.pkl.config.java.Generated` annotation to generated types.
+====
+
 .--rename
 [%collapsible]
 ====

docs/modules/pkl-gradle/partials/gradle-codegen-properties.adoc

@@ -44,6 +44,14 @@ Example: `implementSerializable = true` +
 Whether to generate classes that implement `java.io.Serializable`.
 ====
 
+.addGeneratedAnnotation: Property<Boolean>
+[%collapsible]
+====
+Default: `false` +
+Example: `addGeneratedAnnotation = true` +
+Whether to add the `org.pkl.config.java.Generated` annotation to generated types.
+====
+
 .renames: MapProperty<String, String>
 [%collapsible]
 ====

pkl-codegen-java/src/main/kotlin/org/pkl/codegen/java/CliJavaCodeGeneratorOptions.kt

@@ -29,8 +29,8 @@ data class CliJavaCodeGeneratorOptions(
   /** The characters to use for indenting generated source code. */
   val indent: String = "  ",
 
-  /** Whether to add a <code>@Generated</code> annotation to the types to be generated. */
+  /** Whether to add a `@Generated` annotation to the types to be generated. */
-  val generatedAnnotation: Boolean = false,
+  val addGeneratedAnnotation: Boolean = false,
 
   /**
    * Whether to generate public getter methods and private/protected fields instead of public
@@ -85,7 +85,7 @@ data class CliJavaCodeGeneratorOptions(
   internal fun toJavaCodeGeneratorOptions() =
     JavaCodeGeneratorOptions(
       indent,
-      generatedAnnotation,
+      addGeneratedAnnotation,
       generateGetters,
       generateJavadoc,
       generateSpringBootConfig,

pkl-codegen-java/src/main/kotlin/org/pkl/codegen/java/JavaCodeGenerator.kt

@@ -47,8 +47,8 @@ data class JavaCodeGeneratorOptions(
   /** The characters to use for indenting generated Java code. */
   val indent: String = "  ",
 
-  /** Whether to add a <code>@Generated</code> annotation to the types to be generated. */
+  /** Adds the `org.pkl.config.java.Generated` annotation to the classes to be generated. */
-  val generatedAnnotation: Boolean = false,
+  val addGeneratedAnnotation: Boolean = false,
 
   /**
    * Whether to generate public getter methods and protected final fields instead of public final
@@ -563,7 +563,7 @@ class JavaCodeGenerator(
     fun generateClass(): TypeSpec.Builder {
       val builder =
         TypeSpec.classBuilder(javaPoetClassName.simpleName()).addModifiers(Modifier.PUBLIC)
-      if (codegenOptions.generatedAnnotation) {
+      if (codegenOptions.addGeneratedAnnotation) {
         val name = ClassName.get("org.pkl.config.java", "Generated")
         val generated = AnnotationSpec.builder(name).build()
         builder.addAnnotation(generated)

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

@@ -55,9 +55,9 @@ class PklJavaCodegenCommand : ModulesCommand(name = "pkl-codegen-java", helpLink
       )
       .default(defaults.indent)
 
-  private val generatedAnnotation: Boolean by
+  private val addGeneratedAnnotation: Boolean by
     option(
-        names = arrayOf("--generated-annotation"),
+        names = arrayOf("--add-generated-annotation"),
         help = "Whether to add a @Generated annotation to the types to be generated.",
       )
       .flag()
@@ -139,7 +139,7 @@ class PklJavaCodegenCommand : ModulesCommand(name = "pkl-codegen-java", helpLink
         base = baseOptions.baseOptions(modules, projectOptions),
         outputDir = outputDir,
         indent = indent,
-        generatedAnnotation = generatedAnnotation,
+        addGeneratedAnnotation = addGeneratedAnnotation,
         generateGetters = generateGetters,
         generateJavadoc = generateJavadoc,
         generateSpringBootConfig = generateSpringBoot,

pkl-codegen-java/src/test/kotlin/org/pkl/codegen/java/JavaCodeGeneratorTest.kt

@@ -871,7 +871,7 @@ class JavaCodeGeneratorTest {
       }
     """
           .trimIndent(),
-        JavaCodeGeneratorOptions(generatedAnnotation = true),
+        JavaCodeGeneratorOptions(addGeneratedAnnotation = true),
       )
 
     assertThat(javaCode).compilesSuccessfully().isEqualToResourceFile("GeneratedAnnotation.jva")

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>>
   ) {

pkl-gradle/src/main/java/org/pkl/gradle/PklPlugin.java

@@ -190,7 +190,6 @@ public class PklPlugin implements Plugin<Project> {
           configureBaseSpec(spec);
           configureCodeGenSpec(spec);
 
-          spec.getAddGeneratedAnnotation().convention(false);
           spec.getGenerateGetters().convention(false);
           spec.getGenerateJavadoc().convention(false);
           // Not using `convention()` so that users can disable generation of
@@ -207,7 +206,6 @@ public class PklPlugin implements Plugin<Project> {
               .configure(
                   task -> {
                     configureCodeGenTask(task, spec);
-                    task.getGeneratedAnnotation().set(spec.getAddGeneratedAnnotation());
                     task.getGenerateGetters().set(spec.getGenerateGetters());
                     task.getGenerateJavadoc().set(spec.getGenerateJavadoc());
                     task.getParamsAnnotation().set(spec.getParamsAnnotation());
@@ -354,6 +352,8 @@ public class PklPlugin implements Plugin<Project> {
 
     spec.getImplementSerializable().convention(false);
 
+    spec.getAddGeneratedAnnotation().convention(false);
+
     configureCodeGenSpecModulePath(spec);
   }
 
@@ -454,6 +454,7 @@ public class PklPlugin implements Plugin<Project> {
     task.getOutputDir().set(spec.getOutputDir());
     task.getGenerateSpringBootConfig().set(spec.getGenerateSpringBootConfig());
     task.getImplementSerializable().set(spec.getImplementSerializable());
+    task.getAddGeneratedAnnotation().set(spec.getAddGeneratedAnnotation());
     task.getRenames().set(spec.getRenames());
   }
 

pkl-gradle/src/main/java/org/pkl/gradle/task/CodeGenTask.java

@@ -28,7 +28,7 @@ public abstract class CodeGenTask extends ModulesTask {
 
   @Input
   @Optional
-  public abstract Property<Boolean> getGeneratedAnnotation();
+  public abstract Property<Boolean> getAddGeneratedAnnotation();
 
   @Input
   public abstract Property<String> getIndent();

pkl-gradle/src/main/java/org/pkl/gradle/task/JavaCodeGenTask.java

@@ -47,7 +47,7 @@ public abstract class JavaCodeGenTask extends CodeGenTask {
                 getCliBaseOptions(),
                 getProject().file(getOutputDir()).toPath(),
                 getIndent().get(),
-                getGeneratedAnnotation().get(),
+                getAddGeneratedAnnotation().get(),
                 getGenerateGetters().get(),
                 getGenerateJavadoc().get(),
                 getGenerateSpringBootConfig().get(),

pkl-gradle/src/main/java/org/pkl/gradle/task/KotlinCodeGenTask.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -38,6 +38,7 @@ public abstract class KotlinCodeGenTask extends CodeGenTask {
                 getGenerateKdoc().get(),
                 getGenerateSpringBootConfig().get(),
                 getImplementSerializable().get(),
+                getAddGeneratedAnnotation().get(),
                 getRenames().get()))
         .run();
   }