Cleanup and fix JavaDocs

Author: Jonathing

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/EnhancedFlowAction.java

@@ -22,30 +22,54 @@
 /// The build failure is provided by [org.gradle.api.flow.FlowProviders#getBuildWorkResult()] mapped by
 /// [org.gradle.api.flow.BuildWorkResult#getFailure()].
 public abstract class EnhancedFlowAction<P extends EnhancedFlowAction.EnhancedFlowParameters<?>> implements FlowAction<P> {
-    /// The parameters, including the [#getFailure()] property.
+    /// The parameters, including the [#getFailure()] property and [EnhancedProblems] through [#problems()].
+    ///
+    /// @param <P> The type of [EnhancedProblems] to use
     public static abstract class EnhancedFlowParameters<P extends EnhancedProblems> implements FlowParameters {
         private final Class<P> problemsType;
         private transient @Nullable P problems;
 
         private final Property<Throwable> failure;
 
+        /// The object factory provided by Gradle services.
+        ///
+        /// @return The object factory
+        /// @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#objectfactory">ObjectFactory
+        /// Service Injection</a>
         protected abstract @Inject ObjectFactory getObjects();
 
+        /// The base constructor for the parameters.
+        ///
+        /// @param problemsType The type of enhanced problems that will be accessible through [#problems()].
+        /// @implSpec Must override with `public` and `@`[Inject]
         protected EnhancedFlowParameters(Class<P> problemsType) {
             this.problemsType = problemsType;
 
             this.failure = this.getObjects().property(Throwable.class);
         }
 
+        /// The enhanced problems to be accessed in [EnhancedFlowAction#run(EnhancedFlowParameters)]. They must be
+        /// contained within the parameters as Gradle does not currently support injecting
+        /// [org.gradle.api.problems.Problems] into flow actions.
+        ///
+        /// @return The enhanced problems
+        /// @see <a href="https://github.com/gradle/gradle/issues/33430">gradle#33430</a>
         public P problems() {
             return this.problems == null ? this.problems = this.getObjects().newInstance(this.problemsType) : this.problems;
         }
 
+        /// The failure that was thrown by Gradle. If the build did not fail, this property will not be
+        /// [present][Property#isPresent()].
+        ///
+        /// @return The property for the build failure
         public @Optional @Input Property<Throwable> getFailure() {
             return this.failure;
         }
     }
 
+    /// The base constructor for the flow action.
+    ///
+    /// @implSpec Must override with `public` and `@`[Inject]
     protected EnhancedFlowAction() { }
 
     /// Checks if a given throwable's [message][Throwable#getMessage()] contains the given string

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/EnhancedPlugin.java

@@ -14,7 +14,6 @@
 import org.gradle.api.model.ObjectFactory;
 import org.gradle.api.provider.Provider;
 import org.gradle.api.provider.ProviderFactory;
-import org.jetbrains.annotations.ApiStatus;
 
 import javax.inject.Inject;
 import java.io.File;
@@ -24,29 +23,32 @@
 /// needing to duplicate code across projects.
 ///
 /// @param <T> The type of target
-public abstract class EnhancedPlugin<T> implements Plugin<T> {
+public abstract class EnhancedPlugin<T> implements Plugin<T>, EnhancedPluginAdditions {
     private final String name;
     private final String displayName;
 
     private T target;
     private final EnhancedProblems problemsInternal;
 
-    /**
-     * @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#objectfactory">ObjectFactory
-     * Service Injection</a>
-     */
+    /// The object factory provided by Gradle services.
+    ///
+    /// @return The object factory
+    /// @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#objectfactory">ObjectFactory
+    /// Service Injection</a>
     protected abstract @Inject ObjectFactory getObjects();
 
-    /**
-     * @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#buildlayout">BuildLayout
-     * Service Injection</a>
-     */
+    /// The build layout provided by Gradle services.
+    ///
+    /// @return The build layout
+    /// @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#buildlayout">BuildLayout
+    /// Service Injection</a>
     protected abstract @Inject BuildLayout getBuildLayout();
 
-    /**
-     * @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#providerfactory">ProviderFactory
-     * Service Injection</a>
-     */
+    /// The provider factory provided by Gradle services.
+    ///
+    /// @return The provider factory
+    /// @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#providerfactory">ProviderFactory
+    /// Service Injection</a>
     protected abstract @Inject ProviderFactory getProviders();
 
     /// This constructor must be called by all subclasses using a public constructor annotated with [Inject]. The name
@@ -96,12 +98,8 @@ final EnhancedProblems getProblemsInternal() {
 
     /* TOOLS */
 
-    /// Gets a provider to the file for a [Tool] to be used. The tool's state is managed by Gradle through the
-    /// [org.gradle.api.provider.ValueSource] API and will not cause caching issues.
-    ///
-    /// @param tool The tool to get
-    /// @return A provider for the tool file
     @SuppressWarnings("deprecation") // deprecation intentional, please use this method
+    @Override
     public Provider<File> getTool(Tool tool) {
         return tool.get(this.globalCaches(), this.getProviders());
     }
@@ -111,14 +109,7 @@ public Provider<File> getTool(Tool tool) {
 
     private final Lazy<DirectoryProperty> globalCaches = Lazy.simple(this::makeGlobalCaches);
 
-    /// Gets the global caches to be used for this plugin. These caches persist between projects and should be used to
-    /// eliminate excess work done by projects that request the same data.
-    ///
-    /// It is stored in `~/.gradle/caches/minecraftforge/plugin`.
-    ///
-    /// @return The global caches
-    /// @throws RuntimeException If this plugin cannot access global caches (i.e. the target is not [Project] or
-    ///                          [org.gradle.api.initialization.Settings])
+    @Override
     public final DirectoryProperty globalCaches() {
         return this.globalCaches.get();
     }
@@ -141,14 +132,7 @@ private DirectoryProperty makeGlobalCaches() {
 
     private final Lazy<DirectoryProperty> localCaches = Lazy.simple(this::makeLocalCaches);
 
-    /// Gets the local caches to be used for this plugin. Data done by tasks that should not be shared between projects
-    /// should be stored here.
-    ///
-    /// It is located in `project/build/minecraftforge/plugin`.
-    ///
-    /// @return The global caches
-    /// @throws RuntimeException If this plugin cannot access global caches (i.e. the target is not [Project] or
-    ///                          [org.gradle.api.initialization.Settings])
+    @Override
     public final DirectoryProperty localCaches() {
         return this.localCaches.get();
     }

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/EnhancedPluginAdditions.java

@@ -0,0 +1,37 @@
+package net.minecraftforge.gradleutils.shared;
+
+import org.gradle.api.file.DirectoryProperty;
+import org.gradle.api.provider.Provider;
+
+import java.io.File;
+
+/// This interface defines the additional methods added by [EnhancedPlugin]. They are additionally accessible in tasks
+/// that implement [EnhancedTask].
+public interface EnhancedPluginAdditions {
+    /// Gets a provider to the file for a [Tool] to be used. The tool's state is managed by Gradle through the
+    /// [org.gradle.api.provider.ValueSource] API and will not cause caching issues.
+    ///
+    /// @param tool The tool to get
+    /// @return A provider for the tool file
+    Provider<File> getTool(Tool tool);
+
+    /// Gets the global caches to be used for this plugin. These caches persist between projects and should be used to
+    /// eliminate excess work done by projects that request the same data.
+    ///
+    /// It is stored in `~/.gradle/caches/minecraftforge/plugin`.
+    ///
+    /// @return The global caches
+    /// @throws RuntimeException If this plugin cannot access global caches (i.e. the target is not
+    ///                          [org.gradle.api.Project] or [org.gradle.api.initialization.Settings])
+    DirectoryProperty globalCaches();
+
+    /// Gets the local caches to be used for this plugin. Data done by tasks that should not be shared between projects
+    /// should be stored here.
+    ///
+    /// It is located in `project/build/minecraftforge/plugin`.
+    ///
+    /// @return The global caches
+    /// @throws RuntimeException If this plugin cannot access global caches (i.e. the target is not
+    ///                          [org.gradle.api.Project] or [org.gradle.api.initialization.Settings])
+    DirectoryProperty localCaches();
+}

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/EnhancedProblems.java

@@ -22,7 +22,6 @@
 import org.gradle.api.provider.ProviderFactory;
 import org.gradle.api.reflect.HasPublicType;
 import org.gradle.api.reflect.TypeOf;
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 import javax.inject.Inject;
@@ -287,15 +286,19 @@ public TypeOf<?> getPublicType() {
 
     /* IMPL INSTANTIATION */
 
-    /** @see <a href="https://docs.gradle.org/current/userguide/reporting_problems.html">Reporting Problems</a> */
+    /// The problems instance provided by Gradle services.
+    ///
+    /// @return The problems instance
+    /// @see <a href="https://docs.gradle.org/current/userguide/reporting_problems.html">Reporting Problems</a>
     protected @Inject Problems getProblems() {
         throw new IllegalStateException();
     }
 
-    /**
-     * @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#providerfactory">ProviderFactory
-     * Service Injection</a>
-     */
+    /// The provider factory provided by Gradle services.
+    ///
+    /// @return The provider factory
+    /// @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#providerfactory">ProviderFactory
+    /// Service Injection</a>
     protected @Inject ProviderFactory getProviders() {
         throw new IllegalStateException();
     }

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/EnhancedTask.java

@@ -11,33 +11,39 @@
 import org.gradle.api.file.RegularFile;
 import org.gradle.api.provider.Provider;
 import org.gradle.api.tasks.Internal;
-import org.jetbrains.annotations.VisibleForTesting;
 
 import java.io.File;
 
 /// The enhanced task contains a handful of helper methods to make working with the enhanced plugin and caches easier.
-public interface EnhancedTask extends Task {
+public interface EnhancedTask extends Task, EnhancedPluginAdditions {
     /// The enhanced plugin type for this task.
     ///
     /// @return The plugin type
     Class<? extends EnhancedPlugin<? super Project>> pluginType();
 
-    @VisibleForTesting
+    /// Gets the enhanced plugin used by this task as defined in [#pluginType()].
+    ///
+    /// @return The enhanced plugin
+    /// @deprecated This method is public only due to the limitations imposed by Java 8. Do not use this. Use
+    /// [Task#getProject()] -> [org.gradle.api.plugins.PluginAware#getPlugins()] ->
+    /// [org.gradle.api.plugins.PluginContainer#getPlugin(Class)].
+    @Deprecated
+    @SuppressWarnings("DeprecatedIsStillUsed")
     default @Internal EnhancedPlugin<? super Project> getPlugin() {
         return this.getProject().getPlugins().getPlugin(this.pluginType());
     }
 
-    /// @see EnhancedPlugin#getTool(Tool)
+    @Override
     default Provider<File> getTool(Tool tool) {
         return this.getPlugin().getTool(tool);
     }
 
-    /// @see EnhancedPlugin#globalCaches()
+    @Override
     default DirectoryProperty globalCaches() {
         return this.getPlugin().globalCaches();
     }
 
-    /// @see EnhancedPlugin#localCaches()
+    @Override
     default DirectoryProperty localCaches() {
         return this.getPlugin().localCaches();
     }

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/Lazy.java

@@ -142,7 +142,7 @@ public boolean isPresent() {
         /// Copies this actionable lazy. This can be useful if you need to split off execution paths and have the same
         /// object with different mutations at a specific time.
         ///
-        /// @return The a new actionable lazy copied from this one
+        /// @return A new actionable lazy copied from this one
         public Actionable<T> copy() {
             Actionable<T> ret = new Actionable<>(this.closure);
             ret.value = this.value;

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/SharedUtil.java

@@ -22,6 +22,7 @@
 import org.gradle.jvm.toolchain.JavaLauncher;
 import org.gradle.jvm.toolchain.JavaToolchainService;
 import org.gradle.jvm.toolchain.JavaToolchainSpec;
+import org.jetbrains.annotations.Contract;
 
 import java.io.File;
 import java.io.OutputStream;
@@ -275,12 +276,29 @@ public static String toString(Dependency dependency) {
 
     //region Properties
 
+    /// Makes a returning-self closure that finalizes a given property using [#finalizeProperty(Property)].
+    ///
+    /// This is best used as the method argument for [org.codehaus.groovy.runtime.DefaultGroovyMethods#tap(Object,
+    /// Closure)], which allows for in-lining property creation in Groovy code.
+    ///
+    /// @param <P> The type of property to finalize
+    /// @return The returning-self closure for finalizing a property
     public static <P extends Property<?>> Closure<P> finalizeProperty() {
         Closure<P> ret = Closures.unaryOperator(SharedUtil::finalizeProperty);
         ret.setResolveStrategy(Closure.DELEGATE_FIRST);
         return ret;
     }
 
+    /// Finalizes the given property to prevent any additional changes from being made to it.
+    ///
+    /// This is done by simply calling [Property#disallowChanges()] and [Property#finalizeValueOnRead()]. These methods
+    /// do not return the object itself, so this helper method exists to in-line property creation without needing to
+    /// reference it again just to call these methods.
+    ///
+    /// @param <P>      The type of property to finalize
+    /// @param property The property to finalize
+    /// @return The property
+    @Contract(value = "_ -> param1", mutates = "param1")
     public static <P extends Property<?>> P finalizeProperty(P property) {
         property.disallowChanges();
         property.finalizeValueOnRead();

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/ToolExecBase.java

@@ -25,6 +25,8 @@
 /// consistent between plugins.
 ///
 /// @param <P> The type of enhanced problems, used for common problems reporting with illegal task arguments
+/// @implSpec Implementing plugins should make a shared subclass named `ToolExec` which all other tool executing tasks
+/// should extend from.
 /// @see JavaExec
 /// @see Tool
 public abstract class ToolExecBase<P extends EnhancedProblems> extends JavaExec {
@@ -33,10 +35,11 @@ public abstract class ToolExecBase<P extends EnhancedProblems> extends JavaExec
     /// The default tool directory (usage is not required).
     protected final DirectoryProperty defaultToolDir;
 
-    /**
-     * @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#sec:projectlayout">ProjectLayout
-     * Service Injection</a>
-     */
+    /// The project layout provided by Gradle services.
+    ///
+    /// @return The project layout
+    /// @see <a href="https://docs.gradle.org/current/userguide/service_injection.html#projectlayout">ProjectLayout
+    /// Service Injection</a>
     protected abstract @Inject ProjectLayout getProjectLayout();
 
     /// Creates a new task instance using the given types and tool information.
@@ -91,6 +94,8 @@ private <T extends FileSystemLocation> Transformer<T, T> ensureFileLocationInter
     @MustBeInvokedByOverriders
     protected void addArguments() { }
 
+    /// @implNote Not invoking this method from an overriding method *will* result in the tool never being executed and
+    /// [#addArguments()] never being run.
     @Override
     public void exec() {
         if (this.getArgs().isEmpty())

gradleutils-shared/src/main/java/net/minecraftforge/gradleutils/shared/package-info.java

@@ -9,6 +9,8 @@
  * that include Forge-specific helper methods.</p>
  **/
 @ApiStatus.Internal
+@NotNullByDefault
 package net.minecraftforge.gradleutils.shared;
 
 import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNullByDefault;