improve javadocs, esp. for configurEach

build.gradle

@@ -263,7 +263,6 @@ publishing {
 				classifier ConstantsJarTask.CONSTANTS_CLASSIFIER
 			}
 
-			// TODO why don't these specify classifiers?
 			// quilt-mappings-<version>-sources.jar
 			artifact sourcesJar
 			// quilt-mappings-<version>-javadoc.jar

buildSrc/src/main/java/quilt/internal/plugin/MappingsVerificationPlugin.java

@@ -1,6 +1,7 @@
 package quilt.internal.plugin;
 
 import org.gradle.api.Project;
+import org.gradle.api.Task;
 import org.gradle.api.plugins.PluginContainer;
 import org.gradle.api.tasks.TaskContainer;
 import org.gradle.api.tasks.TaskProvider;
@@ -25,7 +26,8 @@
  * </ul>
  *
  * If {@link LifecycleBasePlugin} is applied, configures the {@value LifecycleBasePlugin#CHECK_TASK_NAME} task
- * to depend on the {@value MappingLintTask#MAPPING_LINT_TASK_NAME} task, which in turn depends on the
+ * to {@linkplain Task#dependsOn(Object...) depend on} the {@value MappingLintTask#MAPPING_LINT_TASK_NAME} task,
+ * which in turn {@linkplain Task#dependsOn(Object...) depend on} the
  * {@value FindDuplicateMappingFilesTask#FIND_DUPLICATE_MAPPING_FILES_TASK_NAME} task.
  */
 public abstract class MappingsVerificationPlugin implements MappingsProjectPlugin {

buildSrc/src/main/java/quilt/internal/task/EnigmaProfileConsumingTask.java

@@ -13,8 +13,8 @@
 
 /**
  * A task that takes an {@link EnigmaProfile} as input.
- * <p>
- * {@link QuiltMappingsBasePlugin} {@linkplain TaskCollection#configureEach configures} default values.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
  */
 public interface EnigmaProfileConsumingTask extends MappingsTask {
     @Internal("@ServiceReference is @Incubating")

buildSrc/src/main/java/quilt/internal/task/MappingsDirConsumingTask.java

@@ -2,7 +2,13 @@
 
 import org.gradle.api.file.DirectoryProperty;
 import org.gradle.api.tasks.InputDirectory;
+import quilt.internal.plugin.QuiltMappingsBasePlugin;
 
+/**
+ * A task that takes a directory containing mappings as input.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
+ */
 public interface MappingsDirConsumingTask extends MappingsTask {
     @InputDirectory
     DirectoryProperty getMappingsDir();

buildSrc/src/main/java/quilt/internal/task/QuiltMappingsArtifactTask.java

@@ -11,9 +11,8 @@
  * <p>
  * Has no effect if the implementing task isn't a subclass of either
  * {@link ArtifactFileTask} or {@link AbstractArchiveTask}.
- * <p>
- * {@link QuiltMappingsBasePlugin} {@linkplain TaskCollection#configureEach(Action) configures}
- * the base name and the version.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
  */
 public interface QuiltMappingsArtifactTask extends MappingsTask {
     static boolean isInstance(Task task) {

buildSrc/src/main/java/quilt/internal/task/VersionDownloadInfoConsumingTask.java

@@ -2,14 +2,13 @@
 
 import org.gradle.api.provider.Property;
 import org.gradle.api.tasks.Input;
-import org.gradle.api.tasks.TaskCollection;
 import quilt.internal.plugin.MinecraftJarsPlugin;
 import quilt.internal.util.VersionDownloadInfo;
 
 /**
  * A task that takes {@link VersionDownloadInfo} as input.
- * <p>
- * {@link MinecraftJarsPlugin} {@linkplain TaskCollection#configureEach configures} some defaults.
+ *
+ * @see MinecraftJarsPlugin MinecraftJarsPlugin's configureEach
  */
 public interface VersionDownloadInfoConsumingTask extends MappingsTask {
     @Input

buildSrc/src/main/java/quilt/internal/task/build/AddProposedMappingsTask.java

@@ -38,10 +38,18 @@
 import org.jetbrains.annotations.VisibleForTesting;
 import quilt.internal.Constants.Groups;
 import quilt.internal.plugin.MapMinecraftJarsPlugin;
+import quilt.internal.plugin.QuiltMappingsBasePlugin;
 import quilt.internal.task.DefaultMappingsTask;
 import quilt.internal.task.EnigmaProfileConsumingTask;
+import quilt.internal.util.EnigmaProfileService;
 import quilt.internal.util.ProviderUtil;
 
+/**
+ * Runs {@link Enigma} to add any proposed mappings from proposers configured in the passed
+ * {@linkplain #getEnigmaProfileService() Enigma profile}.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
+ */
 public abstract class AddProposedMappingsTask extends DefaultMappingsTask implements EnigmaProfileConsumingTask {
     /**
      * {@linkplain TaskContainer#register Registered} by {@link MapMinecraftJarsPlugin}.

buildSrc/src/main/java/quilt/internal/task/build/BuildMappingsTinyTask.java

@@ -14,10 +14,14 @@
 import quilt.internal.Constants.Groups;
 import quilt.internal.Constants.Namespaces;
 import quilt.internal.plugin.MapMinecraftJarsPlugin;
+import quilt.internal.plugin.QuiltMappingsBasePlugin;
 import quilt.internal.task.DefaultMappingsTask;
 import quilt.internal.task.MappingsDirConsumingTask;
 import quilt.internal.util.ProviderUtil;
 
+/**
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
+ */
 public abstract class BuildMappingsTinyTask extends DefaultMappingsTask implements MappingsDirConsumingTask {
     /**
      * {@linkplain TaskContainer#register Registered} by {@link MapMinecraftJarsPlugin}.

buildSrc/src/main/java/quilt/internal/task/build/CompressTinyTask.java

@@ -19,10 +19,8 @@
 
 /**
  * Compresses the input {@link #getMappings() mappings} using GZip.
- * <p>
- * {@link QuiltMappingsBasePlugin} {@linkplain TaskCollection#configureEach configures} a default
- * {@link ArtifactFileTask#getArtifactBaseName() archiveBaseName} and
- * {@link ArtifactFileTask#getArtifactVersion() archiveVersion}.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
  */
 public abstract class CompressTinyTask extends DefaultMappingsTask implements
         ArtifactFileTask, QuiltMappingsArtifactTask {

buildSrc/src/main/java/quilt/internal/task/build/DropInvalidMappingsTask.java

@@ -8,9 +8,17 @@
 import org.gradle.api.tasks.TaskAction;
 import quilt.internal.Constants.Groups;
 import quilt.internal.plugin.MapMinecraftJarsPlugin;
+import quilt.internal.plugin.QuiltMappingsBasePlugin;
 import quilt.internal.task.DefaultMappingsTask;
 import quilt.internal.task.MappingsDirConsumingTask;
 
+/**
+ * Removes any invalid mappings found in the passed {@link #getMappingsDir() mappingsDir}.
+ * <p>
+ * Invalid mappings are usually the result of differences between Minecraft versions.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
+ */
 public abstract class DropInvalidMappingsTask extends DefaultMappingsTask implements MappingsDirConsumingTask {
     /**
      * {@linkplain TaskContainer#register Registered} by {@link MapMinecraftJarsPlugin}.

buildSrc/src/main/java/quilt/internal/task/build/GeneratePackageInfoMappingsTask.java

@@ -15,6 +15,7 @@
 import org.objectweb.asm.tree.ClassNode;
 import quilt.internal.Constants.Groups;
 import quilt.internal.plugin.MapMinecraftJarsPlugin;
+import quilt.internal.plugin.QuiltMappingsBasePlugin;
 import quilt.internal.task.DefaultMappingsTask;
 import quilt.internal.task.mappings.MappingsDirOutputtingTask;
 
@@ -30,6 +31,9 @@
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipFile;
 
+/**
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
+ */
 public abstract class GeneratePackageInfoMappingsTask extends DefaultMappingsTask implements MappingsDirOutputtingTask {
     /**
      * {@linkplain TaskContainer#register Registered} by {@link MapMinecraftJarsPlugin}.

buildSrc/src/main/java/quilt/internal/task/build/IntermediaryMappingsV2JarTask.java

@@ -1,22 +1,21 @@
 package quilt.internal.task.build;
 
-import org.gradle.api.tasks.TaskCollection;
 import org.gradle.api.tasks.TaskContainer;
-import org.gradle.api.tasks.bundling.AbstractArchiveTask;
 import quilt.internal.Constants;
 import quilt.internal.Constants.Namespaces;
 import quilt.internal.plugin.MapIntermediaryPlugin;
+import quilt.internal.plugin.MapV2Plugin;
 import quilt.internal.plugin.QuiltMappingsBasePlugin;
 import quilt.internal.task.setup.IntermediaryDependantTask;
 
 import javax.inject.Inject;
 
 /**
  * Creates a jar file containing {@value Constants#INTERMEDIARY_MAPPINGS_NAME} mappings in Quilt's v2 mapping format.
- * <p>
- * {@link QuiltMappingsBasePlugin} {@linkplain TaskCollection#configureEach configures} a default
- * {@link AbstractArchiveTask#getArchiveBaseName() archiveBaseName} and
- * {@link AbstractArchiveTask#getArchiveVersion() archiveVersion}.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
+ * @see MapIntermediaryPlugin MapIntermediaryPlugin's configureEach
+ * @see MapV2Plugin MapV2Plugin's configureEach
  */
 public abstract class IntermediaryMappingsV2JarTask extends MappingsV2JarTask implements IntermediaryDependantTask {
     /**

buildSrc/src/main/java/quilt/internal/task/build/MappingsV2JarTask.java

@@ -4,9 +4,7 @@
 
 import org.gradle.api.file.RegularFileProperty;
 import org.gradle.api.tasks.InputFile;
-import org.gradle.api.tasks.TaskCollection;
 import org.gradle.api.tasks.TaskContainer;
-import org.gradle.api.tasks.bundling.AbstractArchiveTask;
 import org.gradle.jvm.tasks.Jar;
 import org.gradle.work.DisableCachingByDefault;
 import quilt.internal.Constants.Groups;
@@ -18,13 +16,9 @@
 
 /**
  * Creates a jar file with Quilt's v2 mapping format.
- * <p>
- * {@link QuiltMappingsBasePlugin} {@linkplain TaskCollection#configureEach configures} a default
- * {@link AbstractArchiveTask#getArchiveBaseName() archiveBaseName} and
- * {@link AbstractArchiveTask#getArchiveVersion() archiveVersion}.<br>
- * {@link MapV2Plugin} {@linkplain TaskCollection#configureEach configures} a default
- * {@link MappingsV2JarTask#getUnpickMeta() unpickMeta} and
- * {@link MappingsV2JarTask#getUnpickDefinition() unpickDefinition}.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
+ * @see MapV2Plugin MapV2Plugin's configureEach
  */
 
 // TODO why?

buildSrc/src/main/java/quilt/internal/task/build/MergeIntermediaryTask.java

@@ -3,8 +3,11 @@
 import net.fabricmc.mappingio.MappingVisitor;
 import net.fabricmc.mappingio.adapter.MappingDstNsReorder;
 
+import org.gradle.api.Task;
 import org.gradle.api.file.RegularFileProperty;
+import org.gradle.api.specs.Spec;
 import org.gradle.api.tasks.InputFile;
+import org.gradle.api.tasks.TaskCollection;
 import org.gradle.api.tasks.TaskContainer;
 import org.jetbrains.annotations.VisibleForTesting;
 import quilt.internal.Constants;
@@ -18,6 +21,9 @@
 import java.nio.file.Path;
 import java.util.List;
 
+/**
+ * @see MapIntermediaryPlugin MapIntermediaryPlugin's configureEach
+ */
 public abstract class MergeIntermediaryTask extends AbstractTinyMergeTask implements IntermediaryDependantTask {
     /**
      * {@linkplain TaskContainer#register Registered} by {@link MapIntermediaryPlugin}.

buildSrc/src/main/java/quilt/internal/task/build/RemoveIntermediaryTask.java

@@ -6,10 +6,14 @@
 import net.fabricmc.mappingio.format.MappingFormat;
 import net.fabricmc.mappingio.format.tiny.Tiny2FileWriter;
 import net.fabricmc.mappingio.tree.MemoryMappingTree;
+
+import org.gradle.api.Task;
 import org.gradle.api.file.RegularFileProperty;
+import org.gradle.api.specs.Spec;
 import org.gradle.api.tasks.InputFile;
 import org.gradle.api.tasks.OutputFile;
 import org.gradle.api.tasks.TaskAction;
+import org.gradle.api.tasks.TaskCollection;
 import org.gradle.api.tasks.TaskContainer;
 import org.jetbrains.annotations.VisibleForTesting;
 import quilt.internal.Constants.Groups;
@@ -24,6 +28,12 @@
 import java.nio.file.Path;
 import java.util.Collections;
 
+/**
+ * TODO is this (and the name) accurate? It looks like it actually replaces official with intermediary.<br><br>
+ * Removes the {@value Namespaces#INTERMEDIARY} namespace from the {@link #getInput() input} mappings.
+ *
+ * @see MapIntermediaryPlugin MapIntermediaryPlugin's configureEach
+ */
 public abstract class RemoveIntermediaryTask extends DefaultMappingsTask implements IntermediaryDependantTask {
     /**
      * {@linkplain TaskContainer#register Registered} by {@link MapIntermediaryPlugin}.

buildSrc/src/main/java/quilt/internal/task/build/TinyJarTask.java

@@ -13,10 +13,8 @@
 
 /**
  * Creates a jar file with the input {@link #getMappings() mappings} located at {@value JAR_MAPPINGS_PATH}.
- * <p>
- * {@link QuiltMappingsBasePlugin} {@linkplain TaskCollection#configureEach configures} a default
- * {@link AbstractArchiveTask#getArchiveBaseName() archiveBaseName} and
- * {@link AbstractArchiveTask#getArchiveVersion() archiveVersion}.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
  */
 public abstract class TinyJarTask extends Jar implements QuiltMappingsArtifactTask {
     /**

buildSrc/src/main/java/quilt/internal/task/diff/RemapTargetMinecraftJarTask.java

@@ -2,8 +2,12 @@
 
 import quilt.internal.Constants.Groups;
 import quilt.internal.Constants.Namespaces;
+import quilt.internal.plugin.MapMinecraftJarsPlugin;
 import quilt.internal.task.jarmapping.MapJarTask;
 
+/**
+ * @see MapMinecraftJarsPlugin MapMinecraftJarsPlugin's configureEach
+ */
 public abstract class RemapTargetMinecraftJarTask extends MapJarTask implements UnpickVersionsMatchConsumingTask {
     public static final String REMAP_TARGET_MINECRAFT_JAR_TASK_NAME = "remapTargetMinecraftJar";
 

buildSrc/src/main/java/quilt/internal/task/jarmapping/MapJarTask.java

@@ -16,9 +16,9 @@
 import quilt.internal.util.JarRemapper;
 
 /**
- * Creates a jar file by applying mappings to an input jar.
- * <p>
- * {@link MapMinecraftJarsPlugin} {@linkplain TaskCollection#configureEach configures} some defaults.
+ * Copies a {@linkplain #getInputJar() Jar} and applies {@linkplain #getMappingsFile() mappings}.
+ *
+ * @see MapMinecraftJarsPlugin MapMinecraftJarsPlugin's configureEach
  */
 public abstract class MapJarTask extends DefaultMappingsTask {
     public static final Map<String, String> JAVAX_TO_JETBRAINS = Map.of(

buildSrc/src/main/java/quilt/internal/task/jarmapping/MapNamedJarTask.java

@@ -3,8 +3,12 @@
 import org.gradle.api.tasks.TaskContainer;
 import quilt.internal.Constants.Groups;
 import quilt.internal.Constants.Namespaces;
+import quilt.internal.plugin.MapMinecraftJarsPlugin;
 import quilt.internal.plugin.MapV2Plugin;
 
+/**
+ * @see MapMinecraftJarsPlugin MapMinecraftJarsPlugin's configureEach
+ */
 public abstract class MapNamedJarTask extends MapJarTask {
     /**
      * {@linkplain TaskContainer#register Registered} by {@link MapV2Plugin}.

buildSrc/src/main/java/quilt/internal/task/jarmapping/MapPerVersionMappingsJarTask.java

@@ -5,6 +5,9 @@
 import quilt.internal.Constants.Namespaces;
 import quilt.internal.plugin.MapMinecraftJarsPlugin;
 
+/**
+ * @see MapMinecraftJarsPlugin MapMinecraftJarsPlugin's configureEach
+ */
 public abstract class MapPerVersionMappingsJarTask extends MapJarTask {
     /**
      * {@linkplain TaskContainer#register Registered} by {@link MapMinecraftJarsPlugin}.

buildSrc/src/main/java/quilt/internal/task/lint/FindDuplicateMappingFilesTask.java

@@ -7,6 +7,7 @@
 import org.gradle.api.tasks.TaskAction;
 import quilt.internal.Constants.Groups;
 import quilt.internal.plugin.MappingsVerificationPlugin;
+import quilt.internal.plugin.QuiltMappingsBasePlugin;
 import quilt.internal.task.DefaultMappingsTask;
 import quilt.internal.task.MappingsDirConsumingTask;
 
@@ -17,12 +18,25 @@
 import java.nio.file.Path;
 import java.util.stream.Stream;
 
+/**
+ * Searches the passed {@link #getMappingsDir() mappingsDir} for any mappings files that map the same class.<br>
+ * The task fails if any duplicates or other errors are found.
+ * <p>
+ * Duplicate mappings are usually the result of running {@code git merge/rebase} and
+ * inadvertently combining two histories that give the same class two different names.
+ * <p>
+ * Any file that's empty or that lacks the {@value MAPPING_EXTENSION} extension will also be reported.
+ *
+ * @see QuiltMappingsBasePlugin QuiltMappingsBasePlugin's configureEach
+ */
 public abstract class FindDuplicateMappingFilesTask extends DefaultMappingsTask implements MappingsDirConsumingTask {
     /**
      * {@linkplain org.gradle.api.tasks.TaskContainer#register Registered} by {@link MappingsVerificationPlugin}.
      */
     public static final String FIND_DUPLICATE_MAPPING_FILES_TASK_NAME = "findDuplicateMappingFiles";
 
+    public static final String MAPPING_EXTENSION = "mapping";
+
     private static final Pattern EXPECTED_CLASS =
         Pattern.compile("^CLASS (?:net/minecraft|com/mojang/blaze3d)/(?:\\w+/)*\\w+(?= )");
 
@@ -57,15 +71,15 @@ public void run() {
                             emptyFiles.add(mappingFile);
                         }
 
-                        if (!mappingFile.toString().endsWith(".mapping")) {
+                        if (!mappingFile.toString().endsWith("." + MAPPING_EXTENSION)) {
                             wrongExtensionFiles.add(mappingFile);
                         }
                     } catch (IOException e) {
-                        throw new GradleException("Unexpected error accessing mapping file", e);
+                        throw new GradleException("Unexpected error accessing " + MAPPING_EXTENSION + " file", e);
                     }
                 });
         } catch (IOException e) {
-            throw new GradleException("Unexpected error accessing mappings directory", e);
+            throw new GradleException("Unexpected error accessing " + MAPPING_EXTENSION + "s directory", e);
         }
 
         final Logger logger = this.getLogger();
@@ -101,7 +115,7 @@ public void run() {
         }
 
         if (!wrongExtensionFiles.isEmpty()) {
-            final String message = "%d file%s without the mapping extension".formatted(
+            final String message = ("%d file%s without the " + MAPPING_EXTENSION + " extension").formatted(
                 wrongExtensionFiles.size(),
                 wrongExtensionFiles.size() == 1 ? "" : "s"
             );