Improve event javadocs based on community feedback, apply jSpecify to more events

This commit is contained in:
Paint_Ninja committed 2025-10-10 14:57:38 +01:00
1 parent 8e09d47cd6
commit 8443262e39
66 files changed
+217 -165

No files matched your search

@@ -16,9 +16,16 @@ import java.util.Collection;
/**
* A small helper class to aid Forge modders in migrating from EventBus 6 to the new EventBus 7.
* <br>
* Refer to the migration guide mentioned in the Forge 1.21.6 announcement or ask in the Forge Discord for help with
* migrating your mod to the new system.
* <p>
* Refer to the <a href="https://gist.github.com/PaintNinja/ad82c224aecee25efac1ea3e2cf19b91">migration guide</a>
* mentioned in the <a href="https://files.minecraftforge.net">Forge 1.21.6 changelog</a> or
* <a href="https://forums.minecraftforge.net/topic/159525-forge-581-minecraft-1218/">1.21.8 announcement</a> on the
* forums, or ask in <a href="https://discord.minecraftforge.net">the Forge Discord</a> for help with migrating your mod
* to the new system.
* </p>
* <p>
* You can also check the updated example code in <a href="https://files.minecraftforge.net">the MDK</a> for the MC
* version you're using.
*/
public final class EventBusMigrationHelper {
public static final EventBusMigrationHelper INSTANCE = new EventBusMigrationHelper(BusGroup.DEFAULT);
@@ -10,9 +10,12 @@ import net.minecraft.client.gui.screens.Screen;
import net.minecraftforge.api.distmarker.Dist;
import net.minecraftforge.client.ClientCommandHandler;
import net.minecraftforge.client.ConfigScreenHandler;
import net.minecraftforge.eventbus.api.bus.BusGroup;
import net.minecraftforge.fml.ModLoadingContext;
import net.minecraftforge.fml.config.IConfigSpec;
import net.minecraftforge.fml.config.ModConfig;
import net.minecraftforge.fml.event.IModBusEvent;
import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext;
import net.minecraftforge.fml.loading.FMLEnvironment;
import net.minecraftforge.network.DualStackUtils;
import net.minecraftforge.versions.forge.ForgeVersion;
@@ -27,10 +30,15 @@ import java.util.function.Supplier;
public class MinecraftForge {
/**
* The EventBus for all the Forge Events.
* A helper for partial source-level back-compat with the old event system used in 1.21.5 and older, that acts as
* a wrapper around {@link BusGroup#DEFAULT}.
*
* Events marked with {@link net.minecraftforge.fml.event.IModBusEvent}
* belong on the ModBus and not this bus
* <p>Please refer to the javadocs for {@link EventBusMigrationHelper} for further information and resources on how
* to properly migrate your mod to the new event system.</p>
*
* <p>Events marked with {@link IModBusEvent} belong on the
* {@linkplain FMLJavaModLoadingContext#getModBusGroup() mod BusGroup} and not on the
* {@linkplain BusGroup#DEFAULT default BusGroup}.</p>
*/
public static final EventBusMigrationHelper EVENT_BUS = EventBusMigrationHelper.INSTANCE;
@@ -54,7 +62,7 @@ public class MinecraftForge {
* @param screenFunction A function that takes the mods screen as an argument and returns your config screen to
* show when the player clicks the config button for your mod on the mods screen.
* <p>You should call {@link Minecraft#setScreen(Screen)} with the provided mods screen for the
* action of your close button, using {@link Screen#minecraft} to get the client instance.</p>
* action of your close button, using {@link Screen#getMinecraft()} to get the client instance.</p>
* @see ModLoadingContext#registerExtensionPoint(Class, Supplier)
* @see ModLoadingContext#registerConfig(ModConfig.Type, IConfigSpec)
*/
@@ -10,6 +10,7 @@ import java.util.Objects;
import net.minecraftforge.eventbus.api.bus.BusGroup;
import net.minecraftforge.eventbus.api.bus.EventBus;
import net.minecraftforge.eventbus.api.event.RecordEvent;
import net.minecraftforge.fml.event.IModBusEvent;
import org.jspecify.annotations.NullMarked;
import org.objectweb.asm.Type;
@@ -24,17 +25,18 @@ import org.objectweb.asm.Type;
public record RegisterCapabilitiesEvent() implements RecordEvent {
public static final EventBus<RegisterCapabilitiesEvent> BUS = EventBus.create(RegisterCapabilitiesEvent.class);
/** @deprecated {@link RegisterCapabilitiesEvent} is no longer an {@link IModBusEvent}, so use {@link #BUS} directly. */
@Deprecated(forRemoval = true, since = "1.21.9")
public static EventBus<RegisterCapabilitiesEvent> getBus(BusGroup modBusGroup) {
return BUS;
}
/**
* Registers a capability to be consumed by others.
* APIs who define the capability should call this.
* This is meant to allow Capability consumers to have soft dependencies on the Capability type.
* But be automatically notified when the Class actually exists. Meaning it's safe to create their implementations.
*
* Registers a capability to be consumed by others.<br>
* APIs who define the capability should call this.<br>
* This is meant to allow Capability consumers to have soft dependencies on the Capability type.<br>
* But be automatically notified when the Class actually exists. Meaning it's safe to create their implementations.<br>
* <br>
* To retrieve the Capability instance, use the {@link CapabilityManager} gets functions.
*/
public <T> void register(Class<T> type) {