[Gradle] Add javadoc comments

playframework · Sep 8, 2023 · d0494a2 · d0494a2
1 parent 3a57806
commit d0494a2
Show file tree

Hide file tree

Showing 8 changed files with 89 additions and 14 deletions.
diff --git a/gradle-twirl/src/main/java/play/twirl/gradle/TwirlCompile.java b/gradle-twirl/src/main/java/play/twirl/gradle/TwirlCompile.java
@@ -26,6 +26,7 @@
 import org.gradle.workers.WorkerExecutor;
 import play.twirl.gradle.internal.TwirlCompileAction;
 
+/** Gradle task for compiling Twirl templates into Scala code. */
 public abstract class TwirlCompile extends SourceTask {
 
   @InputFiles

diff --git a/gradle-twirl/src/main/java/play/twirl/gradle/TwirlExtension.java b/gradle-twirl/src/main/java/play/twirl/gradle/TwirlExtension.java
@@ -5,7 +5,20 @@
 
 import org.gradle.api.provider.Property;
 
+/**
+ * The extension of the plugin allowing for configuring the target Scala version used for the
+ * application.
+ */
 public abstract class TwirlExtension {
 
+  /**
+   * Scala version used for compilation Twirl templates.
+   *
+   * <pre>{@code
+   * twirl {
+   *   scalaVersion.set("3")
+   * }
+   * }</pre>
+   */
   public abstract Property<String> getScalaVersion();
 }
diff --git a/gradle-twirl/src/main/java/play/twirl/gradle/TwirlPlugin.java b/gradle-twirl/src/main/java/play/twirl/gradle/TwirlPlugin.java
@@ -23,7 +23,7 @@
 import play.twirl.gradle.internal.DefaultTwirlSourceDirectorySet;
 import play.twirl.gradle.internal.Gradle7TwirlSourceDirectorySet;
 
-/** A simple 'hello world' plugin. */
+/** A Gradle plugin to compile Twirl templates. */
 public class TwirlPlugin implements Plugin<Project> {
 
   static final String DEFAULT_SCALA_VERSION = "2.13";
@@ -58,7 +58,7 @@ public void apply(final Project project) {
     configureSourceSetDefaults(project, twirlConfiguration);
   }
 
-  /** Get Twirl version from Gradle Plugin MANIFEST.MF */
+  /** Get Twirl compiler version from Gradle Plugin MANIFEST.MF */
   private String getDefaultTwirlVersion() {
     return System.getProperty("twirl.version", getClass().getPackage().getImplementationVersion());
   }
@@ -140,25 +140,24 @@ private TaskProvider<TwirlCompile> createTwirlCompileTask(
             });
   }
 
+  @SuppressWarnings("deprecation")
   private TwirlSourceDirectorySet getTwirlSourceDirectorySet(SourceSet sourceSet) {
     String displayName = ((DefaultSourceSet) sourceSet).getDisplayName();
-    TwirlSourceDirectorySet twirlSourceDirectorySet;
-    if (GradleVersion.current().compareTo(GradleVersion.version("8.0")) < 0) { // Gradle < 8.0
-      twirlSourceDirectorySet =
-          objectFactory.newInstance(
-              Gradle7TwirlSourceDirectorySet.class,
-              objectFactory.sourceDirectorySet("twirl", displayName + " Twirl source"));
-    } else { // Gradle 8+
-      twirlSourceDirectorySet =
-          objectFactory.newInstance(
-              DefaultTwirlSourceDirectorySet.class,
-              objectFactory.sourceDirectorySet("twirl", displayName + " Twirl source"));
-    }
+    TwirlSourceDirectorySet twirlSourceDirectorySet =
+        objectFactory.newInstance(
+            isGradleVersionLessThan("8.0")
+                ? Gradle7TwirlSourceDirectorySet.class
+                : DefaultTwirlSourceDirectorySet.class,
+            objectFactory.sourceDirectorySet("twirl", displayName + " Twirl source"));
     twirlSourceDirectorySet.getFilter().include("**/*.scala.*");
     twirlSourceDirectorySet.getTemplateFormats().convention(DEFAULT_TEMPLATE_FORMATS);
     return twirlSourceDirectorySet;
   }
 
+  static boolean isGradleVersionLessThan(String gradleVersion) {
+    return GradleVersion.current().compareTo(GradleVersion.version(gradleVersion)) < 0;
+  }
+
   static JavaPluginExtension javaPluginExtension(Project project) {
     return extensionOf(project, JavaPluginExtension.class);
   }

diff --git a/gradle-twirl/src/main/java/play/twirl/gradle/TwirlSourceDirectorySet.java b/gradle-twirl/src/main/java/play/twirl/gradle/TwirlSourceDirectorySet.java
@@ -15,11 +15,63 @@
  */
 public interface TwirlSourceDirectorySet extends SourceDirectorySet {
 
+  /**
+   * Custom template formats configured for this source directory set.
+   *
+   * <pre>{@code
+   * sourceSets {
+   *   main {
+   *     twirl {
+   *       templateFormats.put("csv", "play.twirl.api.TxtFormat")
+   *     }
+   *   }
+   * }
+   * }</pre>
+   */
   MapProperty<String, String> getTemplateFormats();
 
+  /**
+   * Imports that should be added to generated source files.
+   *
+   * <pre>{@code
+   * sourceSets {
+   *   main {
+   *     twirl {
+   *       templateImports.add("org.example._")
+   *     }
+   *   }
+   * }
+   * }</pre>
+   */
   SetProperty<String> getTemplateImports();
 
+  /**
+   * Annotations added to constructors in injectable templates.
+   *
+   * <pre>{@code
+   * sourceSets {
+   *   main {
+   *     twirl {
+   *       constructorAnnotations.add("@org.example.MyAnnotation()")
+   *     }
+   *   }
+   * }
+   * }</pre>
+   */
   ListProperty<String> getConstructorAnnotations();
 
+  /**
+   * Source encoding for template files and generated scala files.
+   *
+   * <pre>{@code
+   * sourceSets {
+   *   main {
+   *     twirl {
+   *       sourceEncoding.set("<enc>")
+   *     }
+   *   }
+   * }
+   * }</pre>
+   */
   Property<String> getSourceEncoding();
 }
diff --git a/gradle-twirl/src/main/java/play/twirl/gradle/internal/DefaultTwirlSourceDirectorySet.java b/gradle-twirl/src/main/java/play/twirl/gradle/internal/DefaultTwirlSourceDirectorySet.java
@@ -16,6 +16,7 @@
 import org.gradle.api.provider.SetProperty;
 import play.twirl.gradle.TwirlSourceDirectorySet;
 
+/** Default implementation of {@link TwirlSourceDirectorySet}. */
 public class DefaultTwirlSourceDirectorySet extends DefaultSourceDirectorySet
     implements TwirlSourceDirectorySet {
 

diff --git a/gradle-twirl/src/main/java/play/twirl/gradle/internal/Gradle7TwirlSourceDirectorySet.java b/gradle-twirl/src/main/java/play/twirl/gradle/internal/Gradle7TwirlSourceDirectorySet.java
@@ -6,8 +6,15 @@
 import javax.inject.Inject;
 import org.gradle.api.file.SourceDirectorySet;
 import org.gradle.api.model.ObjectFactory;
+import play.twirl.gradle.TwirlSourceDirectorySet;
 
+/**
+ * Implementation of {@link TwirlSourceDirectorySet} is needed to support Gradle 7.
+ *
+ * @deprecated
+ */
 @Deprecated
+@SuppressWarnings("DeprecatedIsStillUsed")
 public class Gradle7TwirlSourceDirectorySet extends DefaultTwirlSourceDirectorySet {
 
   @Inject

diff --git a/gradle-twirl/src/main/java/play/twirl/gradle/internal/TwirlCompileAction.java b/gradle-twirl/src/main/java/play/twirl/gradle/internal/TwirlCompileAction.java
@@ -12,6 +12,7 @@
 import play.japi.twirl.compiler.TwirlCompiler;
 import scala.io.Codec;
 
+/** Gradle work action that compile one Twirl template. */
 public abstract class TwirlCompileAction implements WorkAction<TwirlCompileParams> {
 
   private static final Logger LOGGER = Logging.getLogger(TwirlCompileAction.class);

diff --git a/gradle-twirl/src/main/java/play/twirl/gradle/internal/TwirlCompileParams.java b/gradle-twirl/src/main/java/play/twirl/gradle/internal/TwirlCompileParams.java
@@ -10,6 +10,7 @@
 import org.gradle.api.provider.SetProperty;
 import org.gradle.workers.WorkParameters;
 
+/** Parameters of compilation work action. */
 public interface TwirlCompileParams extends WorkParameters {
 
   RegularFileProperty getSourceFile();