Generate package-info files for all impl and mixin packages (#2615)

* Generate package-info files for all impl and mixin packages

* Add javadoc to generated package-infos, use multiline string

* Simplify code

* Remove manual ApiStatus.Internal on impl classes

* Update CONTRIBUTING.md to remove ApiStatus.Internal for impl classes

* Fix Gradle deprecations

* Fix more Gradle deprecations

* Add task metadata

* Support client-main split

* Remove workaround for client packages

* Try to fix Gradle 8 deprecations

* Try to fix Gradle 8 deprecations, part 2

I'm hoping that using the SourceDirectorySet instead of converting it to a
Set<File> (which is pointless?) will carry the build dependencies over.

* Add clean packageInfo task

Co-authored-by: modmuss50 <modmuss50@gmail.com>

(cherry picked from commit 0d0f21023d)

.gitignore

@@ -27,6 +27,9 @@ jars/
 out/
 classes/
 
+# Generated sources
+**/src/generated/
+
 # Debug artifacts
 run
 *.log

CONTRIBUTING.md

@@ -145,7 +145,7 @@ Fabric API makes strong backwards compatibility guarantees, by which contributor
     - The annotation is not required on individual members, unless the class itself is not experimental.
 - `@ApiStatus.NonExtendable` should be used for API interfaces or classes that modders must not implement or override, but can't be `final` for some reason.
     - Adding methods to such interfaces or classes is not a breaking change.
-- `@ApiStatus.Internal` is recommended for implementation classes to avoid IDE autocompletion suggesting them. There should be no need for internal methods or classes in the public API package.
+- `@ApiStatus.Internal` is automatically applied to all implementation packages to avoid IDE autocompletion suggesting them. There should be no need for internal methods or classes in the public API package.
 
 ### Naming
 - All names should follow the [Yarn naming standards](https://github.com/FabricMC/yarn/blob/HEAD/CONVENTIONS.md).

build.gradle

@@ -266,6 +266,9 @@ allprojects {
 		source(sourceSets.client.output)
 		source(sourceSets.testmod.output)
 	}
+
+	// Apply to each valid subproject.
+	apply from: rootProject.file('gradle/package-info.gradle')
 }
 
 remapTestmodJar {
@@ -319,8 +322,8 @@ javadoc {
 	allprojects.each {
 		if (it.name == "deprecated") return
 
-		source(it.sourceSets.main.allJava.srcDirs)
-		source(it.sourceSets.client.allJava.srcDirs)
+		source(it.sourceSets.main.allJava)
+		source(it.sourceSets.client.allJava)
 	}
 
 	classpath = files(sourceSets.main.compileClasspath, sourceSets.client.compileClasspath)

fabric-api-base/src/main/java/net/fabricmc/fabric/impl/base/event/PhaseSorting.java

@@ -25,12 +25,10 @@ import java.util.Map;
 import java.util.PriorityQueue;
 
 import com.google.common.annotations.VisibleForTesting;
-import org.jetbrains.annotations.ApiStatus;
 
 /**
  * Contains phase-sorting logic for {@link ArrayBackedEvent}.
  */
-@ApiStatus.Internal
 public class PhaseSorting {
 	@VisibleForTesting
 	public static boolean ENABLE_CYCLE_WARNING = true;

fabric-biome-api-v1/src/main/java/net/fabricmc/fabric/impl/biome/NetherBiomeData.java

@@ -26,7 +26,6 @@ import java.util.stream.Collectors;
 import com.google.common.base.Preconditions;
 import com.mojang.datafixers.util.Pair;
 import com.mojang.logging.LogUtils;
-import org.jetbrains.annotations.ApiStatus;
 import org.slf4j.Logger;
 
 import net.minecraft.registry.RegistryEntryLookup;
@@ -42,7 +41,6 @@ import net.fabricmc.fabric.impl.biome.modification.BuiltInRegistryKeys;
 /**
  * Internal data for modding Vanilla's {@link MultiNoiseBiomeSource.Preset#NETHER}.
  */
-@ApiStatus.Internal
 public final class NetherBiomeData {
 	// Cached sets of the biomes that would generate from Vanilla's default biome source without consideration
 	// for data packs (as those would be distinct biome sources).

fabric-biome-api-v1/src/main/java/net/fabricmc/fabric/impl/biome/TheEndBiomeData.java

@@ -26,7 +26,6 @@ import java.util.stream.Collectors;
 import com.google.common.base.Preconditions;
 import it.unimi.dsi.fastutil.Hash;
 import it.unimi.dsi.fastutil.objects.Object2ObjectOpenCustomHashMap;
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.registry.RegistryEntryLookup;
@@ -41,7 +40,6 @@ import net.minecraft.world.biome.source.util.MultiNoiseUtil;
 /**
  * Internal data for modding Vanilla's {@link TheEndBiomeSource}.
  */
-@ApiStatus.Internal
 public final class TheEndBiomeData {
 	public static final ThreadLocal<RegistryEntryLookup<Biome>> biomeRegistry = new ThreadLocal<>();
 	public static final Set<RegistryKey<Biome>> ADDED_BIOMES = new HashSet<>();

fabric-biome-api-v1/src/main/java/net/fabricmc/fabric/impl/biome/modification/BiomeModificationContextImpl.java

@@ -30,7 +30,6 @@ import java.util.stream.Collectors;
 import com.google.common.base.Suppliers;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 import net.minecraft.registry.RegistryKeys;
@@ -58,7 +57,6 @@ import net.minecraft.world.gen.feature.PlacedFeature;
 
 import net.fabricmc.fabric.api.biome.v1.BiomeModificationContext;
 
-@ApiStatus.Internal
 public class BiomeModificationContextImpl implements BiomeModificationContext {
 	private final DynamicRegistryManager registries;
 	private final Biome biome;

fabric-biome-api-v1/src/main/java/net/fabricmc/fabric/impl/biome/modification/BiomeModificationImpl.java

@@ -26,7 +26,6 @@ import java.util.function.Consumer;
 import java.util.function.Predicate;
 
 import com.google.common.base.Stopwatch;
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.TestOnly;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -42,7 +41,6 @@ import net.fabricmc.fabric.api.biome.v1.BiomeModificationContext;
 import net.fabricmc.fabric.api.biome.v1.BiomeSelectionContext;
 import net.fabricmc.fabric.api.biome.v1.ModificationPhase;
 
-@ApiStatus.Internal
 public class BiomeModificationImpl {
 	private static final Logger LOGGER = LoggerFactory.getLogger(BiomeModificationImpl.class);
 

fabric-biome-api-v1/src/main/java/net/fabricmc/fabric/impl/biome/modification/BiomeModificationMarker.java

@@ -16,13 +16,10 @@
 
 package net.fabricmc.fabric.impl.biome.modification;
 
-import org.jetbrains.annotations.ApiStatus;
-
 /**
  * Prevents double-modification of biomes in the same dynamic registry manager from occurring and fails-fast
  * if it does occur.
  */
-@ApiStatus.Internal
 public interface BiomeModificationMarker {
 	void fabric_markModified();
 }

fabric-biome-api-v1/src/main/java/net/fabricmc/fabric/impl/biome/modification/BiomeSelectionContextImpl.java

@@ -18,14 +18,12 @@ package net.fabricmc.fabric.impl.biome.modification;
 
 import java.util.Optional;
 
-import org.jetbrains.annotations.ApiStatus;
-
-import net.minecraft.registry.RegistryKeys;
-import net.minecraft.registry.tag.TagKey;
 import net.minecraft.registry.DynamicRegistryManager;
 import net.minecraft.registry.Registry;
-import net.minecraft.registry.entry.RegistryEntry;
 import net.minecraft.registry.RegistryKey;
+import net.minecraft.registry.RegistryKeys;
+import net.minecraft.registry.entry.RegistryEntry;
+import net.minecraft.registry.tag.TagKey;
 import net.minecraft.world.biome.Biome;
 import net.minecraft.world.dimension.DimensionOptions;
 import net.minecraft.world.gen.feature.ConfiguredFeature;
@@ -34,7 +32,6 @@ import net.minecraft.world.gen.structure.Structure;
 
 import net.fabricmc.fabric.api.biome.v1.BiomeSelectionContext;
 
-@ApiStatus.Internal
 public class BiomeSelectionContextImpl implements BiomeSelectionContext {
 	private final DynamicRegistryManager dynamicRegistries;
 	private final RegistryKey<Biome> key;

fabric-biome-api-v1/src/main/java/net/fabricmc/fabric/impl/biome/modification/BuiltInRegistryKeys.java

@@ -16,19 +16,16 @@
 
 package net.fabricmc.fabric.impl.biome.modification;
 
-import org.jetbrains.annotations.ApiStatus;
-
-import net.minecraft.registry.RegistryKeys;
 import net.minecraft.registry.BuiltinRegistries;
 import net.minecraft.registry.RegistryEntryLookup;
 import net.minecraft.registry.RegistryKey;
+import net.minecraft.registry.RegistryKeys;
 import net.minecraft.registry.RegistryWrapper;
 import net.minecraft.world.biome.Biome;
 
 /**
  * Utility class for accessing the worldgen data that vanilla uses to generate its vanilla datapack.
  */
-@ApiStatus.Internal
 public final class BuiltInRegistryKeys {
 	private static final RegistryWrapper.WrapperLookup vanillaRegistries = BuiltinRegistries.createWrapperLookup();
 

fabric-dimensions-v1/src/main/java/net/fabricmc/fabric/impl/dimension/FabricDimensionInternals.java

@@ -17,14 +17,12 @@
 package net.fabricmc.fabric.impl.dimension;
 
 import com.google.common.base.Preconditions;
-import org.jetbrains.annotations.ApiStatus;
 
 import net.minecraft.entity.Entity;
 import net.minecraft.server.network.ServerPlayerEntity;
 import net.minecraft.server.world.ServerWorld;
 import net.minecraft.world.TeleportTarget;
 
-@ApiStatus.Internal
 public final class FabricDimensionInternals {
 	private FabricDimensionInternals() {
 		throw new AssertionError();

fabric-dimensions-v1/src/main/java/net/fabricmc/fabric/impl/dimension/Teleportable.java

@@ -16,12 +16,10 @@
 
 package net.fabricmc.fabric.impl.dimension;
 
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.world.TeleportTarget;
 
-@ApiStatus.Internal
 public interface Teleportable {
 	/**
 	 * Sets the last target set when a user of the API requested teleportation, or null.

fabric-rendering-data-attachment-v1/src/main/java/net/fabricmc/fabric/impl/rendering/data/attachment/RenderDataObjectConsumer.java

@@ -17,9 +17,7 @@
 package net.fabricmc.fabric.impl.rendering.data.attachment;
 
 import it.unimi.dsi.fastutil.longs.Long2ObjectOpenHashMap;
-import org.jetbrains.annotations.ApiStatus;
 
-@ApiStatus.Internal
 public interface RenderDataObjectConsumer {
 	void fabric_acceptRenderDataObjects(Long2ObjectOpenHashMap<Object> renderDataObjects);
 }

fabric-resource-loader-v0/src/main/java/net/fabricmc/fabric/impl/resource/loader/ModNioResourcePack.java

@@ -36,7 +36,6 @@ import java.util.Map;
 import java.util.Set;
 import java.util.regex.Pattern;
 
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -55,7 +54,6 @@ import net.fabricmc.fabric.api.resource.ResourcePackActivationType;
 import net.fabricmc.loader.api.ModContainer;
 import net.fabricmc.loader.api.metadata.ModMetadata;
 
-@ApiStatus.Internal
 public class ModNioResourcePack implements ResourcePack, ModResourcePack {
 	private static final Logger LOGGER = LoggerFactory.getLogger(ModNioResourcePack.class);
 	private static final Pattern RESOURCE_PACK_PATH = Pattern.compile("[a-z0-9-_.]+");

fabric-screen-api-v1/src/client/java/net/fabricmc/fabric/impl/client/screen/ButtonList.java

@@ -19,8 +19,6 @@ package net.fabricmc.fabric.impl.client.screen;
 import java.util.AbstractList;
 import java.util.List;
 
-import org.jetbrains.annotations.ApiStatus;
-
 import net.minecraft.client.gui.Selectable;
 import net.minecraft.client.gui.Drawable;
 import net.minecraft.client.gui.Element;
@@ -30,7 +28,6 @@ import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 
 // TODO: When events for listening to addition of child elements are added, fire events from this list.
-@ApiStatus.Internal
 @Environment(EnvType.CLIENT)
 public final class ButtonList extends AbstractList<ClickableWidget> {
 	private final List<Drawable> drawables;

fabric-screen-api-v1/src/client/java/net/fabricmc/fabric/impl/client/screen/ScreenEventFactory.java

@@ -16,8 +16,6 @@
 
 package net.fabricmc.fabric.impl.client.screen;
 
-import org.jetbrains.annotations.ApiStatus;
-
 import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 import net.fabricmc.fabric.api.client.screen.v1.ScreenEvents;
@@ -29,7 +27,6 @@ import net.fabricmc.fabric.api.event.EventFactory;
 /**
  * Factory methods for creating event instances used in {@link ScreenExtensions}.
  */
-@ApiStatus.Internal
 @Environment(EnvType.CLIENT)
 public final class ScreenEventFactory {
 	public static Event<ScreenEvents.Remove> createRemoveEvent() {

fabric-screen-api-v1/src/client/java/net/fabricmc/fabric/impl/client/screen/ScreenExtensions.java

@@ -18,8 +18,6 @@ package net.fabricmc.fabric.impl.client.screen;
 
 import java.util.List;
 
-import org.jetbrains.annotations.ApiStatus;
-
 import net.minecraft.client.gui.screen.Screen;
 import net.minecraft.client.gui.widget.ClickableWidget;
 
@@ -30,7 +28,6 @@ import net.fabricmc.fabric.api.client.screen.v1.ScreenKeyboardEvents;
 import net.fabricmc.fabric.api.client.screen.v1.ScreenMouseEvents;
 import net.fabricmc.fabric.api.event.Event;
 
-@ApiStatus.Internal
 @Environment(EnvType.CLIENT)
 public interface ScreenExtensions {
 	static ScreenExtensions getExtensions(Screen screen) {

fabric-transfer-api-v1/src/main/java/net/fabricmc/fabric/impl/transfer/item/SpecialLogicInventory.java

@@ -16,14 +16,11 @@
 
 package net.fabricmc.fabric.impl.transfer.item;
 
-import org.jetbrains.annotations.ApiStatus;
-
 import net.minecraft.item.ItemStack;
 
 /**
  * Internal class that allows inventory instances to defer special logic until {@link InventorySlotWrapper#onFinalCommit()} is called.
  */
-@ApiStatus.Internal
 public interface SpecialLogicInventory {
 	/**
 	 * Decide whether special logic should now be suppressed. If true, must remain suppressed until the next call.

gradle/package-info.gradle

@@ -0,0 +1,78 @@
+import java.nio.file.Files
+
+for (def sourceSet in [sourceSets.main, sourceSets.client]) {
+	// We have to capture the source set name for the lazy string literals,
+	// otherwise it'll just be whatever the last source set is in the list.
+	def sourceSetName = sourceSet.name
+	def taskName = sourceSet.getTaskName('generate', 'ImplPackageInfos')
+	def task = tasks.register(taskName, GenerateImplPackageInfos) {
+		group = 'fabric'
+		description = "Generates package-info files for $sourceSetName implementation packages."
+
+		// Only apply to default source directory since we also add the generated
+		// sources to the source set.
+		sourceRoot = file("src/$sourceSetName/java")
+		header = rootProject.file('HEADER')
+		outputDir = file("src/generated/$sourceSetName")
+	}
+	sourceSet.java.srcDir task
+
+	def cleanTask = tasks.register(sourceSet.getTaskName('clean', 'ImplPackageInfos'), Delete) {
+		group = 'fabric'
+		delete file("src/generated/$sourceSetName")
+	}
+	clean.dependsOn cleanTask
+}
+
+class GenerateImplPackageInfos extends DefaultTask {
+	@InputFile
+	File header
+
+	@SkipWhenEmpty
+	@InputDirectory
+	final DirectoryProperty sourceRoot = project.objects.directoryProperty()
+
+	@OutputDirectory
+	final DirectoryProperty outputDir = project.objects.directoryProperty()
+
+	@TaskAction
+	def run() {
+		def output = outputDir.get().asFile.toPath()
+		output.deleteDir()
+		def headerText = header.readLines().join("\n") // normalize line endings
+		def root = sourceRoot.get().asFile.toPath()
+
+		for (def dir in ['impl', 'mixin']) {
+			def implDir = root.resolve("net/fabricmc/fabric/$dir")
+
+			if (Files.notExists(implDir)) {
+				continue
+			}
+
+			implDir.eachDirRecurse {
+				def containsJava = Files.list(it).any {
+					Files.isRegularFile(it) && it.fileName.toString().endsWith('.java')
+				}
+
+				if (containsJava && Files.notExists(it.resolve('package-info.java'))) {
+					def relativePath = root.relativize(it)
+					def target = output.resolve(relativePath)
+					Files.createDirectories(target)
+
+					target.resolve('package-info.java').withWriter {
+						def packageName = relativePath.toString().replace(File.separator, '.')
+						it.write("""$headerText
+						|/**
+						| * Implementation code for ${project.name}.
+						| */
+						|@ApiStatus.Internal
+						|package $packageName;
+						|
+						|import org.jetbrains.annotations.ApiStatus;
+						|""".stripMargin())
+					}
+				}
+			}
+		}
+	}
+}