Add Javadocs for all events (#91)

* javadoc for ClientChatEvent

* javadoc for ClientPlayerEvent

* javadoc for ClientRawInputEvent

* Added javadoc for ClientScreenInputEvent

* Bit refactoring and removed javadoc @see to the caller methods

* Add javadoc for BlockEvent

* Add javadoc for ChatEvent

* Add javadoc for CommandPerformEvent and CommandRegistrationEvent

* Add javadoc for EntityEvent

* Add javadoc for ExplosionEvent

* Add javadoc for GuiEvent

* Add javadoc for InteractionEvent

* Add javadoc for LightningEvent, RecipeUpdateEvent & TextureStitchEvent

* Add javadoc for LifecycleEvent & ClientLifecycleEvent

* Add javadoc for TooltipEvent

* Add javadoc for TickEvent and partly PlayerEvent

* More javadoc for PlayerEvent

* Finally all event have javadoc

* Update common/src/main/java/me/shedaniel/architectury/event/events/CommandPerformEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/CommandPerformEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/CommandPerformEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/ChatEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/CommandRegistrationEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/EntityEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/EntityEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/EntityEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/EntityEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/client/ClientScreenInputEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/client/ClientScreenInputEvent.java

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/BlockEvent.java

Co-authored-by: Max <maxh2709@gmail.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/BlockEvent.java

Co-authored-by: Max <maxh2709@gmail.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/BlockEvent.java

Co-authored-by: Max <maxh2709@gmail.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/BlockEvent.java

Co-authored-by: Max <maxh2709@gmail.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/LifecycleEvent.java

Co-authored-by: Max <maxh2709@gmail.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/LifecycleEvent.java

Co-authored-by: Max <maxh2709@gmail.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/LifecycleEvent.java

Co-authored-by: Max <maxh2709@gmail.com>

* Update common/src/main/java/me/shedaniel/architectury/event/events/PlayerEvent.java

Co-authored-by: Max <maxh2709@gmail.com>

* Apply suggestions from code review

Co-authored-by: Max <maxh2709@gmail.com>
Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>
Co-authored-by: Max <maxh2709@gmail.com>

* Apply suggestions from code review

Co-authored-by: Max <maxh2709@gmail.com>
Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Max <maxh2709@gmail.com>
Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Max <maxh2709@gmail.com>
Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: shedaniel <daniel@shedaniel.me>

* Applied some more reviews

* Applied some more reviews

* Applied suggestions

* Reformat and apply some minor suggestions

* Apply suggestions from review (first batch)

* Remove double return javadoc

* Apply suggestions from code review

Co-authored-by: shedaniel <daniel@shedaniel.me>

* Add "scaled" to mouse coordinates

* Final touches

Signed-off-by: shedaniel <daniel@shedaniel.me>

* Remove invalid tips

Signed-off-by: shedaniel <daniel@shedaniel.me>

Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>
Co-authored-by: Max <maxh2709@gmail.com>
Co-authored-by: shedaniel <daniel@shedaniel.me>

common/src/main/java/me/shedaniel/architectury/event/CompoundEventResult.java

@@ -28,7 +28,7 @@ import net.minecraft.world.InteractionResultHolder;
  * @param <T> the type of the extra result
  * @see #pass()
  * @see #interrupt(Boolean, Object)
- * @see CompoundEventResult
+ * @see EventResult
  */
 public class CompoundEventResult<T> {
     private static final CompoundEventResult<?> PASS = new CompoundEventResult<>(EventResult.pass(), null);

common/src/main/java/me/shedaniel/architectury/event/events/BlockEvent.java

@@ -32,32 +32,56 @@ import net.minecraft.world.level.block.state.BlockState;
 import org.jetbrains.annotations.Nullable;
 
 public interface BlockEvent {
-    
-    // Block interaction events
     /**
-     * Called when a player breaks a block.
+     * @see Break#breakBlock(Level, BlockPos, BlockState, ServerPlayer, IntValue)
      */
     Event<Break> BREAK = EventFactory.createInteractionResult();
     /**
-     * Called when a block is placed in the world by an entity.
+     * @see Place#placeBlock(Level, BlockPos, BlockState, Entity)
      */
     Event<Place> PLACE = EventFactory.createInteractionResult();
-    
     /**
-     * Called when a falling block (sand, anvil, etc.) is about to land.
-     * Use fallState#getBlock to get the type of block for more granular control.
+     * @see FallingLand#onLand(Level, BlockPos, BlockState, BlockState, FallingBlockEntity)
      */
     Event<FallingLand> FALLING_LAND = EventFactory.createLoop();
     
     interface Break {
+        /**
+         * Invoked when a block is destroyed by a player.
+         *
+         * @param world  The level the block is in.
+         * @param pos    The position of the block.
+         * @param state  The current state of the block.
+         * @param player The player who is breaking the block.
+         * @param xp     The experience that are dropped when the block was destroyed. Always {@code null} on fabric.
+         * @return Return {@link InteractionResult#FAIL} to cancel the block breaking.
+         */
         InteractionResult breakBlock(Level world, BlockPos pos, BlockState state, ServerPlayer player, @Nullable IntValue xp);
     }
     
     interface Place {
+        /**
+         * Invoked when a block is placed.
+         *
+         * @param world  The level the block is in.
+         * @param pos    The position of the block.
+         * @param state  The future state of the block.
+         * @param placer The entity who is placing it. Can be {@code null}, e.g. when a dispenser places something.
+         * @return Any other value than {@link InteractionResult#PASS} cancels the block placement.
+         */
         InteractionResult placeBlock(Level world, BlockPos pos, BlockState state, @Nullable Entity placer);
     }
     
     interface FallingLand {
+        /**
+         * Invoked when a falling block is about to land.
+         *
+         * @param level     The level the block is in.
+         * @param pos       The position of the block.
+         * @param fallState The current state of the falling block.
+         * @param landOn    The current state of the block the falling one is landing on.
+         * @param entity    The falling block entity.
+         */
         void onLand(Level level, BlockPos pos, BlockState fallState, BlockState landOn, FallingBlockEntity entity);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/ChatEvent.java

@@ -27,11 +27,21 @@ import net.minecraft.world.InteractionResultHolder;
 
 public interface ChatEvent {
     /**
-     * Invoked when server receives a message, equivalent to forge's {@code ServerChatEvent}.
+     * @see Server#process(ServerPlayer, String, Component)
      */
     Event<Server> SERVER = EventFactory.createInteractionResultHolder();
     
     interface Server {
+        /**
+         * Invoked when the server receives a message from a client.
+         * Equivalent to Forge's {@code ServerChatEvent} event.
+         *
+         * @param player    The player who has sent the message.
+         * @param message   The raw message itself.
+         * @param component The message as component.
+         * @return A {@link InteractionResultHolder} determining the outcome of the event,
+         * if an outcome is set, the vanilla message is overridden.
+         */
         InteractionResultHolder<Component> process(ServerPlayer player, String message, Component component);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/CommandPerformEvent.java

@@ -26,34 +26,56 @@ import me.shedaniel.architectury.event.EventFactory;
 import net.minecraft.commands.CommandSourceStack;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * This event is invoked whenever a command is issued.
+ * The {@link ParseResults} can be modified and even a custom {@link Throwable} can be used to tell the source of failure.
+ *
+ * <p>A command fails when any other result than {@link net.minecraft.world.InteractionResult#PASS} is returned.
+ * When PASS is used, the {@link CommandPerformEvent#getResults()} is used for execution.
+ *
+ * <p> Equivalent to Forge's {@code CommandEvent} event.
+ */
 public class CommandPerformEvent {
-    /**
-     * Invoked after server parses a command but before server executes it, equivalent to forge's {@code CommandEvent}.
-     */
     public static final Event<Actor<CommandPerformEvent>> EVENT = EventFactory.createActorLoop();
     
     private ParseResults<CommandSourceStack> results;
     @Nullable
     private Throwable throwable;
     
+    /**
+     * @param results   The initial used parsed results.
+     * @param throwable The initial used throwable.
+     */
     public CommandPerformEvent(ParseResults<CommandSourceStack> results, @Nullable Throwable throwable) {
         this.results = results;
         this.throwable = throwable;
     }
     
+    /**
+     * @return The parsed results for the issued command.
+     */
     public ParseResults<CommandSourceStack> getResults() {
         return results;
     }
     
+    /**
+     * @param results The new results the command should use.
+     */
     public void setResults(ParseResults<CommandSourceStack> results) {
         this.results = results;
     }
     
+    /**
+     * @return An throwable to be used as why the command has failed.
+     */
     @Nullable
     public Throwable getThrowable() {
         return throwable;
     }
     
+    /**
+     * @param throwable The throwable used when the command has failed.
+     */
     public void setThrowable(@Nullable Throwable throwable) {
         this.throwable = throwable;
     }

common/src/main/java/me/shedaniel/architectury/event/events/CommandRegistrationEvent.java

@@ -27,9 +27,16 @@ import net.minecraft.commands.Commands;
 
 public interface CommandRegistrationEvent {
     /**
-     * Invoked after server registers its commands, equivalent to forge's {@code RegisterCommandsEvent} and fabric's {@code CommandRegistrationCallback}.
+     * @see CommandRegistrationEvent#register(CommandDispatcher, Commands.CommandSelection)
      */
     Event<CommandRegistrationEvent> EVENT = EventFactory.createLoop();
     
+    /**
+     * This event is invoked after the server registers it's commands.
+     * Equivalent to Forge's {@code RegisterCommandsEvent} and Fabric's {@code CommandRegistrationCallback}.
+     *
+     * @param dispatcher The command dispatcher to register commands to.
+     * @param selection  The selection where the command can be executed.
+     */
     void register(CommandDispatcher<CommandSourceStack> dispatcher, Commands.CommandSelection selection);
 }

common/src/main/java/me/shedaniel/architectury/event/events/EntityEvent.java

@@ -24,6 +24,7 @@ import me.shedaniel.architectury.event.EventFactory;
 import me.shedaniel.architectury.event.EventResult;
 import net.minecraft.core.BlockPos;
 import net.minecraft.world.InteractionResult;
+import net.minecraft.world.InteractionResultHolder;
 import net.minecraft.world.damagesource.DamageSource;
 import net.minecraft.world.entity.Entity;
 import net.minecraft.world.entity.LivingEntity;
@@ -37,23 +38,23 @@ import org.jetbrains.annotations.Nullable;
 
 public interface EntityEvent {
     /**
-     * Invoked before LivingEntity#die, equivalent to forge's {@code LivingDeathEvent}.
+     * @see LivingDeath#die(LivingEntity, DamageSource)
      */
     Event<LivingDeath> LIVING_DEATH = EventFactory.createInteractionResult();
     /**
-     * Invoked before LivingEntity#hurt, equivalent to forge's {@code LivingAttackEvent}.
+     * @see LivingAttack#attack(LivingEntity, DamageSource, float)
      */
     Event<LivingAttack> LIVING_ATTACK = EventFactory.createInteractionResult();
     /**
-     * Invoked when an entity is about to be spawned, equivalent to forge's {@code LivingSpawnEvent.CheckSpawn}
+     * @see LivingCheckSpawn#canSpawn(LivingEntity, LevelAccessor, double, double, double, MobSpawnType, BaseSpawner)
      */
     Event<LivingCheckSpawn> LIVING_CHECK_SPAWN = EventFactory.createEventResult();
     /**
-     * Invoked before entity is added to a world, equivalent to forge's {@code EntityJoinWorldEvent}.
+     * @see Add#add(Entity, Level)
      */
     Event<Add> ADD = EventFactory.createInteractionResult();
     /**
-     * Invoked when an entity enters a chunk,  equivalent to forge's {@code EnteringChunk}
+     * @see EnterChunk#enterChunk(Entity, int, int, int, int)
      */
     Event<EnterChunk> ENTER_CHUNK = EventFactory.createLoop();
     
@@ -65,26 +66,79 @@ public interface EntityEvent {
     Event<PlaceBlock> PLACE_BLOCK = EventFactory.createInteractionResult();
     
     interface LivingDeath {
+        /**
+         * Invoked before a living entity dies.
+         * Equivalent to Forge's {@code LivingDeathEvent} event.
+         *
+         * @param entity The entity that is about to die.
+         * @param source The source of damage triggering the death.
+         * @return Returning {@link InteractionResult#FAIL} prevents the entity from dying.
+         */
         InteractionResult die(LivingEntity entity, DamageSource source);
     }
     
     interface LivingAttack {
+        /**
+         * Invoked before an entity is hurt by a damage source.
+         * Equivalent to Forge's {@code LivingAttackEvent} event.
+         *
+         * <p>You currently cannot override the amount of damage the entity receives.
+         *
+         * @param entity The entity that is attacked.
+         * @param source The reason why the entity takes damage.
+         * @param amount The amount of damage the entity takes.
+         * @return Returning {@link InteractionResult#FAIL} prevents the entity from taking damage.
+         */
         InteractionResult attack(LivingEntity entity, DamageSource source, float amount);
     }
     
     interface LivingCheckSpawn {
+        /**
+         * Invoked before an entity is spawned into the world.
+         * This specifically concerns <i>spawning</i> through either a {@link BaseSpawner} or during world generation.
+         * Equivalent to Forge's {@code LivingSpawnEvent.CheckSpawn} event.
+         *
+         * @param entity  The entity that is about to spawn.
+         * @param world   The level the entity wants to spawn in.
+         * @param x       The x-coordinate of the spawn position.
+         * @param y       The y-coordinate of the spawn position.
+         * @param z       The z-coordinate the spawn position.
+         * @param type    The source of spawning.
+         * @param spawner The spawner. Can be {@code null}.
+         * @return A {@link InteractionResultHolder} determining the outcome of the event,
+         * if an outcome is set, the vanilla result is overridden.
+         */
         EventResult canSpawn(LivingEntity entity, LevelAccessor world, double x, double y, double z, MobSpawnType type, @Nullable BaseSpawner spawner);
     }
     
     interface Add {
+        /**
+         * Invoked when an entity is about to be added to the world.
+         * Equivalent to Forge's {@code EntityJoinWorldEvent} event.
+         *
+         * @param entity The entity to add to the level.
+         * @param world  The level the entity is added to.
+         * @return Returning {@link InteractionResult#FAIL} prevents the addition of the entity to the world.
+         */
         InteractionResult add(Entity entity, Level world);
     }
     
+    @Deprecated
     interface PlaceBlock {
         InteractionResult placeBlock(Level world, BlockPos pos, BlockState state, @Nullable Entity placer);
     }
     
     interface EnterChunk {
+        /**
+         * Invoked whenever an entity enters a chunk.
+         * Equivalent to Forge's {@code EnteringChunk} event.
+         *
+         * @param entity The entity moving to a different chunk.
+         * @param chunkX The chunk x-coordinate.
+         * @param chunkZ The chunk z-coordinate.
+         * @param prevX  The previous chunk x-coordinate.
+         * @param prevZ  The previous chunk z-coordinate.
+         */
         void enterChunk(Entity entity, int chunkX, int chunkZ, int prevX, int prevZ);
     }
     

common/src/main/java/me/shedaniel/architectury/event/events/ExplosionEvent.java

@@ -29,14 +29,36 @@ import net.minecraft.world.level.Level;
 import java.util.List;
 
 public interface ExplosionEvent {
+    /**
+     * @see Pre#explode(Level, Explosion)
+     */
     Event<Pre> PRE = EventFactory.createInteractionResult();
+    /**
+     * @see Detonate#explode(Level, Explosion, List)
+     */
     Event<Detonate> DETONATE = EventFactory.createLoop();
     
     interface Pre {
+        /**
+         * Invoked before an explosion happens.
+         * Equivalent to Forge's {@code ExplosionEvent.Start} event.
+         *
+         * @param world     The level the explosion is happening in.
+         * @param explosion The explosion.
+         * @return Returning {@link InteractionResult#FAIL} cancels the explosion.
+         */
         InteractionResult explode(Level world, Explosion explosion);
     }
     
     interface Detonate {
+        /**
+         * Invoked when an explosion is detonating.
+         * Equivalent to Forge's {@code ExplosionEvent.Detonate} event.
+         *
+         * @param world            The level the explosion happens in.
+         * @param explosion        The explosion happening.
+         * @param affectedEntities The entities affected by the explosion.
+         */
         void explode(Level world, Explosion explosion, List<Entity> affectedEntities);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/GuiEvent.java

@@ -35,59 +35,127 @@ import java.util.List;
 @Environment(EnvType.CLIENT)
 public interface GuiEvent {
     /**
-     * Invoked after in-game hud is rendered, equivalent to forge's {@code RenderGameOverlayEvent.Post@ElementType#ALL} and fabric's {@code HudRenderCallback}.
+     * @see RenderHud#renderHud(PoseStack, float)
      */
     Event<RenderHud> RENDER_HUD = EventFactory.createLoop();
+    /**
+     * @see DebugText#gatherText(List)
+     */
     Event<DebugText> DEBUG_TEXT_LEFT = EventFactory.createLoop();
     Event<DebugText> DEBUG_TEXT_RIGHT = EventFactory.createLoop();
     /**
-     * Invoked during Screen#init after previous widgets are cleared, equivalent to forge's {@code GuiScreenEvent.InitGuiEvent.Pre}.
+     * @see ScreenInitPre#init(Screen, List, List)
      */
     Event<ScreenInitPre> INIT_PRE = EventFactory.createInteractionResult();
     /**
-     * Invoked after Screen#init, equivalent to forge's {@code GuiScreenEvent.InitGuiEvent.Post}.
+     * @see ScreenInitPost#init(Screen, List, List)
      */
     Event<ScreenInitPost> INIT_POST = EventFactory.createLoop();
+    /**
+     * @see ScreenRenderPre#render(Screen, PoseStack, int, int, float)
+     */
     Event<ScreenRenderPre> RENDER_PRE = EventFactory.createInteractionResult();
+    /**
+     * @see ScreenRenderPost#render(Screen, PoseStack, int, int, float)
+     */
     Event<ScreenRenderPost> RENDER_POST = EventFactory.createLoop();
-    
     /**
-     * Invoked during Minecraft#setScreen, equivalent to forge's {@code GuiOpenEvent}.
+     * @see SetScreen#modifyScreen(Screen)
      */
     Event<SetScreen> SET_SCREEN = EventFactory.createInteractionResultHolder();
     
     @Environment(EnvType.CLIENT)
     interface RenderHud {
+        /**
+         * Invoked after the in-game hud has been rendered.
+         * Equivalent to Forge's {@code RenderGameOverlayEvent.Post@ElementType#ALL} and Fabric's {@code HudRenderCallback}.
+         *
+         * @param matrices  The pose stack.
+         * @param tickDelta The tick delta.
+         */
         void renderHud(PoseStack matrices, float tickDelta);
     }
     
     @Environment(EnvType.CLIENT)
     interface DebugText {
+        /**
+         * Invoked when the debug text is being gathered for rendering.
+         * There are two different versions of this event, one for the left and one for the right side.
+         * Equivalent to Forge's {@code RenderGameOverlayEvent.Text}, when {@code Minecraft.getInstance().options.renderDebug} is true.
+         *
+         * @param strings The current debug text strings.
+         */
         void gatherText(List<String> strings);
     }
     
     @Environment(EnvType.CLIENT)
     interface ScreenInitPre {
+        /**
+         * Invoked when a screen is being initialized and after the previous widgets have been cleared.
+         * Equivalent to Forge's {@code GuiScreenEvent.InitGuiEvent.Pre} event.
+         *
+         * @param screen   The screen.
+         * @param widgets  The widgets of the screen.
+         * @param children The listeners of the screen.
+         * @return Returning {@link InteractionResult#FAIL} results in the rest of the init method being ignored.
+         */
         InteractionResult init(Screen screen, List<AbstractWidget> widgets, List<GuiEventListener> children);
     }
     
     @Environment(EnvType.CLIENT)
     interface ScreenInitPost {
+        /**
+         * Invoked after a screen has been initialized and all the vanilla initialization logic has happened.
+         * Equivalent to Forge's {@code GuiScreenEvent.InitGuiEvent.Post} event.
+         *
+         * @param screen   The screen.
+         * @param widgets  The widgets of the screen.
+         * @param children The listeners of the screen.
+         */
         void init(Screen screen, List<AbstractWidget> widgets, List<GuiEventListener> children);
     }
     
     @Environment(EnvType.CLIENT)
     interface ScreenRenderPre {
+        /**
+         * Invoked before any screen is rendered.
+         * Equivalent to Forge's {@code GuiScreenEvent.DrawScreenEvent.Pre} event.
+         *
+         * @param screen   The screen.
+         * @param matrices The pose stack.
+         * @param mouseX   The scaled x-coordinate of the mouse cursor.
+         * @param mouseY   The scaled y-coordinate of the mouse cursor.
+         * @param delta    The current tick delta.
+         * @return Returning {@link InteractionResult#FAIL} prevents any other rendering.
+         */
         InteractionResult render(Screen screen, PoseStack matrices, int mouseX, int mouseY, float delta);
     }
     
     @Environment(EnvType.CLIENT)
     interface ScreenRenderPost {
+        /**
+         * Invoked after a screen has finished rendering using the vanilla logic.
+         * Equivalent to Forge's {@code GuiScreenEvent.DrawScreenEvent.Post} event.
+         *
+         * @param screen   The screen.
+         * @param matrices The pose stack.
+         * @param mouseX   The scaled x-coordinate of the mouse cursor.
+         * @param mouseY   The scaled y-coordinate of the mouse cursor.
+         * @param delta    The current tick delta.
+         */
         void render(Screen screen, PoseStack matrices, int mouseX, int mouseY, float delta);
     }
     
     @Environment(EnvType.CLIENT)
     interface SetScreen {
+        /**
+         * Invoked before a new screen is set to open.
+         * Equivalent to Forge's {@code GuiOpenEvent} event.
+         *
+         * @param screen The screen that is going to be opened.
+         * @return A {@link InteractionResultHolder} determining the outcome of the event,
+         * if an outcome is set, the vanilla screen is overridden.
+         */
         InteractionResultHolder<Screen> modifyScreen(Screen screen);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/InteractionEvent.java

@@ -32,48 +32,136 @@ import net.minecraft.world.entity.player.Player;
 import net.minecraft.world.item.ItemStack;
 import net.minecraft.world.level.Level;
 import net.minecraft.world.level.block.state.BlockState;
+import org.jetbrains.annotations.ApiStatus;
 
 public interface InteractionEvent {
+    /**
+     * @see LeftClickBlock#click(Player, InteractionHand, BlockPos, Direction)
+     */
     Event<LeftClickBlock> LEFT_CLICK_BLOCK = EventFactory.createInteractionResult();
+    /**
+     * @see RightClickBlock#click(Player, InteractionHand, BlockPos, Direction)
+     */
     Event<RightClickBlock> RIGHT_CLICK_BLOCK = EventFactory.createInteractionResult();
+    /**
+     * @see RightClickItem#click(Player, InteractionHand)
+     */
     Event<RightClickItem> RIGHT_CLICK_ITEM = EventFactory.createInteractionResultHolder();
+    /**
+     * @see ClientLeftClickAir#click(Player, InteractionHand)
+     */
     Event<ClientLeftClickAir> CLIENT_LEFT_CLICK_AIR = EventFactory.createLoop();
+    /**
+     * @see ClientRightClickAir#click(Player, InteractionHand)
+     */
     Event<ClientRightClickAir> CLIENT_RIGHT_CLICK_AIR = EventFactory.createLoop();
+    /**
+     * @see InteractEntity#interact(Player, Entity, InteractionHand)
+     */
     Event<InteractEntity> INTERACT_ENTITY = EventFactory.createInteractionResult();
     /**
-     * Invoked before a farmland block is trampled by an entity, equivalent to forge's {@code BlockEvent.FarmlandTrampleEvent}
+     * @see FarmlandTrample#trample(Level, BlockPos, BlockState, float, Entity)
      */
     Event<FarmlandTrample> FARMLAND_TRAMPLE = EventFactory.createEventResult();
     
     interface RightClickBlock {
+        /**
+         * Invoked whenever a player right clicks a block.
+         * Equivalent to Forge's {@code PlayerInteractEvent.RightClickBlock} event and Fabric's {@code UseBlockCallback}.
+         *
+         * @param player The player right clicking the block.
+         * @param hand   The hand that is used.
+         * @param pos    The position of the block in the level.
+         * @param face   The face of the block clicked.
+         * @return The event is canceled if anything else than {@link InteractionResult#PASS} is returned.
+         */
         InteractionResult click(Player player, InteractionHand hand, BlockPos pos, Direction face);
     }
     
     interface LeftClickBlock {
+        /**
+         * Invoked whenever a player left clicks a block.
+         * Equivalent to Forge's {@code PlayerInteractEvent.LeftClickBlock} event and Fabric's {@code AttackBlockCallback}.
+         *
+         * @param player The player left clicking the block.
+         * @param hand   The hand that is used.
+         * @param pos    The position of the block in the level. Use {@link Player#getCommandSenderWorld()} to get the level.
+         * @param face   The face of the block clicked.
+         * @return The event is canceled if anything else than {@link InteractionResult#PASS} is returned.
+         */
         InteractionResult click(Player player, InteractionHand hand, BlockPos pos, Direction face);
     }
     
     interface RightClickItem {
+        /**
+         * Invoked whenever a player uses an item on a block.
+         * Equivalent to Forge's {@code PlayerInteractEvent.RightClickItem} event and Fabric's {@code UseItemCallback}.
+         *
+         * @param player The player right clicking the block.
+         * @param hand   The hand that is used.
+         * @return Whenever the return is not {@link InteractionResult#PASS}, the result value is used and the event is canceled.
+         */
         InteractionResultHolder<ItemStack> click(Player player, InteractionHand hand);
     }
     
     interface ClientRightClickAir {
+        /**
+         * Invoked whenever a player right clicks the air.
+         * This only occurs on the client.
+         * Equivalent to Forge's {@code PlayerInteractEvent.RightClickEmpty} event.
+         *
+         * @param player The player. Always {@link net.minecraft.client.player.LocalPlayer}
+         * @param hand   The hand used.
+         */
         void click(Player player, InteractionHand hand);
     }
     
     interface ClientLeftClickAir {
+        /**
+         * Invoked whenever a player left clicks the air.
+         * This only occurs on the client.
+         * Equivalent to Forge's {@code PlayerInteractEvent.LeftClickEmpty} event.
+         *
+         * @param player The player. Always {@link net.minecraft.client.player.LocalPlayer}
+         * @param hand   The hand used.
+         */
         void click(Player player, InteractionHand hand);
     }
     
     interface InteractEntity {
+        /**
+         * Invoked whenever a player right clicks an entity.
+         * Equivalent to Forge's {@code PlayerInteractEvent.EntityInteract} event.
+         *
+         * @param player The player clicking the entity.
+         * @param entity Then entity the player clicks.
+         * @param hand   The used hand.
+         * @return If the return value is not {@link InteractionResult#PASS}, event is cancelled and the used result is passed as return value.
+         */
         InteractionResult interact(Player player, Entity entity, InteractionHand hand);
     }
     
+    /**
+     * @deprecated use {@link BlockEvent#BREAK}
+     */
+    @ApiStatus.ScheduledForRemoval(inVersion = "2.0")
+    @Deprecated
     interface BlockBreak {
         InteractionResult breakBlock(Player player, BlockPos pos, BlockState state);
     }
     
     interface FarmlandTrample {
+        /**
+         * Invoked when an entity attempts to trample farmland.
+         * Equivalent to Forge's {@code BlockEvent.FarmlandTrampleEvent} event.
+         *
+         * @param world    The level where the block and the player are located in.
+         * @param pos      The position of the block.
+         * @param state    The state of the block.
+         * @param distance The distance of the player to the block.
+         * @param entity   The entity trampling.
+         * @return The event callback result.
+         */
         EventResult trample(Level world, BlockPos pos, BlockState state, float distance, Entity entity);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/LifecycleEvent.java

@@ -27,39 +27,74 @@ import net.minecraft.world.level.Level;
 
 public interface LifecycleEvent {
     /**
-     * Invoked when server is starting, equivalent to forge's {@code FMLServerAboutToStartEvent} and fabric's {@code ServerLifecycleEvents#SERVER_STARTING}.
+     * Invoked before initial server startup. This is the earliest point at which the server will be available.
+     * Equivalent to Forge's {@code FMLServerAboutToStartEvent} event and
+     * Fabric's {@code ServerLifecycleEvents#SERVER_STARTING}.
+     *
+     * @see ServerState#stateChanged(Object)
      */
     Event<ServerState> SERVER_BEFORE_START = EventFactory.createLoop();
     /**
-     * Invoked when server is starting, equivalent to forge's {@code FMLServerStartingEvent}.
+     * Invoked during server startup.
+     * Equivalent to Forge's {@code FMLServerStartingEvent} event.
+     *
+     * @see ServerState#stateChanged(Object)
      */
     Event<ServerState> SERVER_STARTING = EventFactory.createLoop();
     /**
-     * Invoked when server has started, equivalent to forge's {@code FMLServerStartedEvent} and fabric's {@code ServerLifecycleEvents#SERVER_STARTED}.
+     * Invoked when the server has started and is ready to accept players.
+     * Equivalent to Forge's {@code FMLServerStartedEvent} event
+     * and Fabric's {@code ServerLifecycleEvents#SERVER_STARTED}.
+     *
+     * @see ServerState#stateChanged(Object)
      */
     Event<ServerState> SERVER_STARTED = EventFactory.createLoop();
     /**
-     * Invoked when server is stopping, equivalent to forge's {@code FMLServerStoppingEvent} and fabric's {@code ServerLifecycleEvents#SERVER_STOPPING}.
+     * Invoked when the server begins shutting down.
+     * Equivalent to Forge's {@code FMLServerStoppingEvent} event and
+     * Fabric's {@code ServerLifecycleEvents#SERVER_STOPPING}.
+     *
+     * @see ServerState#stateChanged(Object)
      */
     Event<ServerState> SERVER_STOPPING = EventFactory.createLoop();
     /**
-     * Invoked when server has stopped, equivalent to forge's {@code FMLServerStoppedEvent} and fabric's {@code ServerLifecycleEvents#SERVER_STOPPED}.
+     * Invoked when the server has finished stopping, and is about to fully shut down.
+     * Equivalent to Forge's {@code FMLServerStoppedEvent} event and
+     * Fabric's {@code ServerLifecycleEvents#SERVER_STOPPED}.
+     *
+     * @see ServerState#stateChanged(Object)
      */
     Event<ServerState> SERVER_STOPPED = EventFactory.createLoop();
     /**
-     * Invoked after a world is loaded only on server, equivalent to forge's {@code WorldEvent.Load} and fabric's {@code ServerWorldEvents#LOAD}.
+     * Invoked when a world is loaded on the server-side.
+     * Equivalent to Forge's {@code WorldEvent.Load} event (on server)
+     * and Fabric's {@code ServerWorldEvents#LOAD}.
+     *
+     * @see ServerWorldState#act(Level)
      */
     Event<ServerWorldState> SERVER_WORLD_LOAD = EventFactory.createLoop();
     /**
-     * Invoked after a world is unloaded, equivalent to forge's {@code WorldEvent.Unload} and fabric's {@code ServerWorldEvents#UNLOAD}.
+     * Invoked when a world is unloaded on the server-side.
+     * Equivalent to Forge's {@code WorldEvent.Unload} event (on server)
+     * and Fabric's {@code ServerWorldEvents#UNLOAD}.
+     *
+     * @see ServerWorldState#act(Level)
      */
     Event<ServerWorldState> SERVER_WORLD_UNLOAD = EventFactory.createLoop();
     /**
-     * Invoked during a world is saved, equivalent to forge's {@code WorldEvent.Save}.
+     * Invoked when the world is being saved.
+     * Equivalent to Forge's {@code WorldEvent.Save} event.
+     *
+     * @see ServerWorldState#act(Level)
      */
     Event<ServerWorldState> SERVER_WORLD_SAVE = EventFactory.createLoop();
     
     interface InstanceState<T> {
+        /**
+         * Parent event type for any events that are invoked on instance state change.
+         *
+         * @param instance The changed state.
+         */
         void stateChanged(T instance);
     }
     
@@ -67,6 +102,11 @@ public interface LifecycleEvent {
     }
     
     interface WorldState<T extends Level> {
+        /**
+         * Parent event type for any events that are invoked on world state change.
+         *
+         * @param world The world that has changed.
+         */
         void act(T world);
     }
     

common/src/main/java/me/shedaniel/architectury/event/events/LightningEvent.java

@@ -30,15 +30,22 @@ import java.util.List;
 
 public interface LightningEvent {
     
-    // TODO Pre - Called before a lightning bolt entity is added to the world. (cancellable)
+    // TODO Pre - Invoked before a lightning bolt entity is added to the world. (cancellable)
     /**
-     * Invoked after the lightning has gathered a list of entities to strike.
-     * Remove entities from the list to stop them from being hit.
+     * @see Strike#onStrike(LightningBolt, Level, Vec3, List)
      */
     Event<Strike> STRIKE = EventFactory.createLoop();
-    // TODO Post - Called before a lightning bolt entity is removed from the world.
+    // TODO Post - Invoked before a lightning bolt entity is removed from the world.
     
     interface Strike {
+        /**
+         * Invoked after the lightning has gathered a list of entities to strike.
+         *
+         * @param bolt     The lightning bolt.
+         * @param level    The level the lighting is spawned in.
+         * @param pos      The position the lightning strikes.
+         * @param toStrike A list of all entities the lightning affects.
+         */
         void onStrike(LightningBolt bolt, Level level, Vec3 pos, List<Entity> toStrike);
     }
     

common/src/main/java/me/shedaniel/architectury/event/events/PlayerEvent.java

@@ -40,25 +40,60 @@ import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 public interface PlayerEvent {
+    /**
+     * @see PlayerJoin#join(ServerPlayer)
+     */
     Event<PlayerJoin> PLAYER_JOIN = EventFactory.createLoop();
+    /**
+     * @see PlayerQuit#quit(ServerPlayer)
+     */
     Event<PlayerQuit> PLAYER_QUIT = EventFactory.createLoop();
+    /**
+     * @see PlayerRespawn#respawn(ServerPlayer, boolean)
+     */
     Event<PlayerRespawn> PLAYER_RESPAWN = EventFactory.createLoop();
+    /**
+     * @see PlayerAdvancement#award(ServerPlayer, Advancement)
+     */
     Event<PlayerAdvancement> PLAYER_ADVANCEMENT = EventFactory.createLoop();
+    /**
+     * @see PlayerClone#clone(ServerPlayer, ServerPlayer, boolean)
+     */
     Event<PlayerClone> PLAYER_CLONE = EventFactory.createLoop();
+    /**
+     * @see CraftItem#craft(Player, ItemStack, Container)
+     */
     Event<CraftItem> CRAFT_ITEM = EventFactory.createLoop();
+    /**
+     * @see SmeltItem#smelt(Player, ItemStack)
+     */
     Event<SmeltItem> SMELT_ITEM = EventFactory.createLoop();
+    /**
+     * @see PickupItemPredicate#canPickup(Player, ItemEntity, ItemStack)
+     */
     Event<PickupItemPredicate> PICKUP_ITEM_PRE = EventFactory.createInteractionResult();
+    /**
+     * @see PickupItem#pickup(Player, ItemEntity, ItemStack)
+     */
     Event<PickupItem> PICKUP_ITEM_POST = EventFactory.createLoop();
+    /**
+     * @see ChangeDimension#change(ServerPlayer, ResourceKey, ResourceKey)
+     */
     Event<ChangeDimension> CHANGE_DIMENSION = EventFactory.createLoop();
+    /**
+     * @see DropItem#drop(Player, ItemEntity)
+     */
     Event<DropItem> DROP_ITEM = EventFactory.createLoop();
+    /**
+     * @see OpenMenu#open(Player, AbstractContainerMenu)
+     */
     Event<OpenMenu> OPEN_MENU = EventFactory.createLoop();
+    /**
+     * @see CloseMenu#close(Player, AbstractContainerMenu)
+     */
     Event<CloseMenu> CLOSE_MENU = EventFactory.createLoop();
     /**
-     * Invoked when a player attempts to fill a bucket using right-click.
-     * You can return a non-PASS interaction result to cancel further processing by other mods.
-     * <p>
-     * On Forge, FAIL cancels the event, and SUCCESS sets the event as handled.
-     * On Fabric, any non-PASS result is returned directly and immediately.
+     * @see FillBucket#fill(Player, Level, ItemStack, HitResult)
      */
     Event<FillBucket> FILL_BUCKET = EventFactory.createCompoundEventResult();
     
@@ -70,62 +105,177 @@ public interface PlayerEvent {
     Event<BreakBlock> BREAK_BLOCK = EventFactory.createInteractionResult();
     
     interface PlayerJoin {
+        /**
+         * Invoked after a player joined a server level.
+         * Equivalent to Forge's {@code PlayerLoggedInEvent} event.
+         *
+         * @param player The joined player.
+         */
         void join(ServerPlayer player);
     }
     
     interface PlayerQuit {
+        /**
+         * Invoked after a player logged out of a server level.
+         * Equivalent to Forge's {@code PlayerLoggedOutEvent} event.
+         *
+         * @param player The now logged out player.
+         */
         void quit(ServerPlayer player);
     }
     
     interface PlayerRespawn {
+        /**
+         * Invoked when a player is respawned (e.g. changing dimension).
+         * Equivalent to Forge's {@code PlayerRespawnEvent} event.
+         * To manipulate the player use {@link PlayerClone#clone(ServerPlayer, ServerPlayer, boolean)}.
+         *
+         * @param newPlayer    The respawned player.
+         * @param conqueredEnd Whether the player has conquered the end. This is true when the player joined the end and now is leaving it. {@link ServerPlayer#wonGame}
+         */
         void respawn(ServerPlayer newPlayer, boolean conqueredEnd);
     }
     
     interface PlayerClone {
+        /**
+         * Invoked when a player respawns.
+         * This can be used to manipulate the new player.
+         * Equivalent to Forge's {@code PlayerEvent.Clone} event.
+         *
+         * @param oldPlayer The old player.
+         * @param newPlayer The new player.
+         * @param wonGame   This is true when the player joined the end and now is leaving it. {@link ServerPlayer#wonGame}
+         */
         void clone(ServerPlayer oldPlayer, ServerPlayer newPlayer, boolean wonGame);
     }
     
     interface PlayerAdvancement {
+        /**
+         * Invoked when a player gets an advancement.
+         * Equivalent to Forge's {@code AdvancementEvent} event.
+         *
+         * @param player      The player who got the advancement.
+         * @param advancement The advancement the player got.
+         */
         void award(ServerPlayer player, Advancement advancement);
     }
     
     interface CraftItem {
+        /**
+         * Invoked when a player crafts an item.
+         * Equivalent to Forge's {@code ItemCraftedEvent} event.
+         * This only applies for the vanilla crafting table (or any crafting table using the {@link net.minecraft.world.inventory.ResultSlot}) and
+         * the player inventory crafting grid.
+         * This is invoked when the player takes something out of the result slot.
+         *
+         * @param player      The player.
+         * @param constructed The ItemStack that has been crafted.
+         * @param inventory   The inventory of the constructor.
+         */
         void craft(Player player, ItemStack constructed, Container inventory);
     }
     
     interface SmeltItem {
+        /**
+         * Invoked when a player smelts an item.
+         * Equivalent to Forge's {@code ItemSmeltedEvent} event.
+         * This is invoked when the player takes the stack out of the output slot.
+         *
+         * @param player  The player.
+         * @param smelted The smelt result.
+         */
         void smelt(Player player, ItemStack smelted);
     }
     
     interface PickupItemPredicate {
+        /**
+         * Invoked when a player tries to pickup an {@link ItemEntity}.
+         * Equivalent to Forge's {@code EntityItemPickupEvent} event.
+         *
+         * @param player The player picking up.
+         * @param entity The {@link ItemEntity} that the player tries to pick up.
+         * @param stack  The content of the {@link ItemEntity}.
+         * @return Forge ignores the return value. On Fabric a {@link InteractionResult#FAIL} results in the event getting canceled and the item not being picked up.
+         */
         InteractionResult canPickup(Player player, ItemEntity entity, ItemStack stack);
     }
     
     interface PickupItem {
+        /**
+         * Invoked when a player has picked up an {@link ItemEntity}.
+         * Equivalent to Forge's {@code ItemPickupEvent} event.
+         *
+         * @param player The player.
+         * @param entity The {@link ItemEntity} that the player picked up.
+         * @param stack  The content of the {@link ItemEntity}.
+         */
         void pickup(Player player, ItemEntity entity, ItemStack stack);
     }
     
     interface ChangeDimension {
+        /**
+         * Invoked when a player changes their dimension.
+         * Equivalent to Forge's {@code PlayerChangedDimensionEvent} event.
+         *
+         * @param player   The teleporting player.
+         * @param oldLevel The level the player comes from.
+         * @param newLevel The level the player teleports into.
+         */
         void change(ServerPlayer player, ResourceKey<Level> oldLevel, ResourceKey<Level> newLevel);
     }
     
     interface DropItem {
+        /**
+         * Invoked when a player drops an item.
+         * Equivalent to Forge's {@code ItemTossEvent} event.
+         *
+         * @param player The player dropping something.
+         * @param entity The entity that has spawned when the player dropped a ItemStack.
+         * @return Forge ignores the return value. On Fabric a {@link InteractionResult#FAIL} results in the event getting canceled and the item not being dropped.
+         */
         InteractionResult drop(Player player, ItemEntity entity);
     }
     
     interface BreakBlock {
+        /**
+         * Deprecated variant of {@link BlockEvent#BREAK}. Defers to the proper event.
+         */
         InteractionResult breakBlock(Level world, BlockPos pos, BlockState state, ServerPlayer player, @Nullable IntValue xp);
     }
     
     interface OpenMenu {
+        /**
+         * Invoked when a player opens a menu.
+         * Equivalent to Forge's {@code PlayerContainerEvent.Open} event.
+         *
+         * @param player The player opening the menu.
+         * @param menu   The menu that is opened.
+         */
         void open(Player player, AbstractContainerMenu menu);
     }
     
     interface CloseMenu {
+        /**
+         * Invoked when a player closes a menu.
+         * Equivalent to Forge's {@code PlayerContainerEvent.Close} event.
+         *
+         * @param player The player closing the menu.
+         * @param menu   The menu that is closed.
+         */
         void close(Player player, AbstractContainerMenu menu);
     }
     
     interface FillBucket {
+        /**
+         * Invoked when a player attempts to fill a bucket using right-click.
+         * You can return a non-PASS interaction result to cancel further processing by other mods.
+         *
+         * @param player The player filling the bucket.
+         * @param level  The level the player is in.
+         * @param stack  The bucket stack.
+         * @param target The target which the player has aimed at.
+         * @return A {@link CompoundEventResult} determining the outcome of the event.
+         */
         CompoundEventResult<ItemStack> fill(Player player, Level level, ItemStack stack, @Nullable HitResult target);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/RecipeUpdateEvent.java

@@ -27,7 +27,16 @@ import net.minecraft.world.item.crafting.RecipeManager;
 
 @Environment(EnvType.CLIENT)
 public interface RecipeUpdateEvent {
+    /**
+     * @see RecipeUpdateEvent#update(RecipeManager)
+     */
     Event<RecipeUpdateEvent> EVENT = EventFactory.createLoop();
     
+    /**
+     * Invoked when the client has received an updated list of recipes from the server.
+     * Equivalent to Forge's {@code RecipesUpdatedEvent} event.
+     *
+     * @param recipeManager The recipe manager.
+     */
     void update(RecipeManager recipeManager);
 }

common/src/main/java/me/shedaniel/architectury/event/events/TextureStitchEvent.java

@@ -30,16 +30,35 @@ import java.util.function.Consumer;
 
 @Environment(EnvType.CLIENT)
 public interface TextureStitchEvent {
+    /**
+     * @see Pre#stitch(TextureAtlas, Consumer)
+     */
     Event<Pre> PRE = EventFactory.createLoop();
+    /**
+     * @see Post#stitch(TextureAtlas)
+     */
     Event<Post> POST = EventFactory.createLoop();
     
     @Environment(EnvType.CLIENT)
     interface Pre {
+        /**
+         * Invoked before the texture atlas is stitched together.
+         * Equivalent to Forge's {@code TextureStitchEvent.Pre} event.
+         *
+         * @param atlas       The TextureAtlas.
+         * @param spriteAdder A consumer where you can add your own sprites to be stitched.
+         */
         void stitch(TextureAtlas atlas, Consumer<ResourceLocation> spriteAdder);
     }
     
     @Environment(EnvType.CLIENT)
     interface Post {
+        /**
+         * Invoked after the texture atlas has been fully stitched.
+         * Equivalent to Forge's {@code TextureStitchEvent.Post} event.
+         *
+         * @param atlas The ready-to-use TextureAtlas.
+         */
         void stitch(TextureAtlas atlas);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/TickEvent.java

@@ -26,13 +26,54 @@ import net.minecraft.server.level.ServerLevel;
 import net.minecraft.world.level.Level;
 
 public interface TickEvent<T> {
+    /**
+     * Invoked before a server tick is processed.
+     * Equivalent to Forge's {@code ServerTickEvent} event in the START Phase.
+     *
+     * @see #tick(Object)
+     */
     Event<Server> SERVER_PRE = EventFactory.createLoop();
+    /**
+     * Invoked after a server tick has been processed.
+     * Equivalent to Forge's {@code ServerTickEvent} event in the END Phase.
+     *
+     * @see #tick(Object)
+     */
     Event<Server> SERVER_POST = EventFactory.createLoop();
+    /**
+     * Invoked before a server level tick is processed.
+     * Equivalent to Forge's {@code WorldTickEvent} event in the START Phase.
+     *
+     * @see #tick(Object)
+     */
     Event<ServerWorld> SERVER_WORLD_PRE = EventFactory.createLoop();
+    /**
+     * Invoked after a server level tick has been processed.
+     * Equivalent to Forge's {@code WorldTickEvent} event in the END Phase.
+     *
+     * @see #tick(Object)
+     */
     Event<ServerWorld> SERVER_WORLD_POST = EventFactory.createLoop();
+    /**
+     * Invoked before a player tick is processed.
+     * Equivalent to Forge's {@code PlayerTickEvent} event in the START Phase.
+     *
+     * @see #tick(Object)
+     */
     Event<Player> PLAYER_PRE = EventFactory.createLoop();
+    /**
+     * Invoked after a player tick has been processed.
+     * Equivalent to Forge's {@code PlayerTickEvent} event in the END Phase.
+     *
+     * @see #tick(Object)
+     */
     Event<Player> PLAYER_POST = EventFactory.createLoop();
     
+    /**
+     * Callback method for tick events.
+     *
+     * @param instance The object ticking.
+     */
     void tick(T instance);
     
     interface Server extends TickEvent<MinecraftServer> {

common/src/main/java/me/shedaniel/architectury/event/events/TooltipEvent.java

@@ -35,40 +35,98 @@ import java.util.List;
 
 @Environment(EnvType.CLIENT)
 public interface TooltipEvent {
+    /**
+     * @see Item#append(ItemStack, List, TooltipFlag)
+     */
     Event<Item> ITEM = EventFactory.createLoop();
     /**
-     * Render vanilla events are not invoked on the forge side.
+     * @see RenderVanilla#renderTooltip(PoseStack, List, int, int)
      */
     Event<RenderVanilla> RENDER_VANILLA_PRE = EventFactory.createInteractionResult();
     /**
-     * Render forge events are only invoked on the forge side.
+     * @see RenderForge#renderTooltip(PoseStack, List, int, int)
      */
     Event<RenderForge> RENDER_FORGE_PRE = EventFactory.createInteractionResult();
+    /**
+     * @see RenderModifyPosition#renderTooltip(PoseStack, PositionContext)
+     */
     Event<RenderModifyPosition> RENDER_MODIFY_POSITION = EventFactory.createLoop();
+    /**
+     * @see RenderModifyColor#renderTooltip(PoseStack, int, int, ColorContext)
+     */
     Event<RenderModifyColor> RENDER_MODIFY_COLOR = EventFactory.createLoop();
     
     @Environment(EnvType.CLIENT)
     interface Item {
+        /**
+         * Invoked whenever an item tooltip is rendered.
+         * Equivalent to Forge's {@code ItemTooltipEvent} event and
+         * Fabric's {@code ItemTooltipCallback}.
+         *
+         * @param stack The rendered stack.
+         * @param lines The mutable list of tooltip components.
+         * @param flag  A flag indicating if advanced mode is active.
+         */
         void append(ItemStack stack, List<Component> lines, TooltipFlag flag);
     }
     
     @Environment(EnvType.CLIENT)
     interface RenderVanilla {
+        /**
+         * Invoked before the tooltip for a tooltip is rendered.
+         *
+         * <p> This is <b>not</b> invoked on Forge due to
+         * {@link RenderForge#renderTooltip(PoseStack, List, int, int) fundamental differences}
+         * in Forge and vanilla tooltip logic.
+         *
+         * @param matrices The pose stack.
+         * @param texts    The mutable list of components that are rendered.
+         * @param x        The x-coordinate of the tooltip.
+         * @param y        The y-coordinate of the tooltip.
+         * @return Returning {@link InteractionResult#FAIL} cancels the rendering.
+         */
         InteractionResult renderTooltip(PoseStack matrices, List<? extends FormattedCharSequence> texts, int x, int y);
     }
     
     @Environment(EnvType.CLIENT)
     interface RenderForge {
+        /**
+         * Invoked before the tooltip for a tooltip is rendered.
+         *
+         * <p> This is <b>only</b> invoked on Forge due to
+         * {@link RenderVanilla#renderTooltip(PoseStack, List, int, int) fundamental differences}
+         * in Forge and vanilla tooltip logic.
+         *
+         * @param matrices The pose stack.
+         * @param texts    The mutable list of components that are rendered.
+         * @param x        The x-coordinate of the tooltip.
+         * @param y        The y-coordinate of the tooltip.
+         * @return Returning {@link InteractionResult#FAIL} cancels the rendering.
+         */
         InteractionResult renderTooltip(PoseStack matrices, List<? extends FormattedText> texts, int x, int y);
     }
     
     @Environment(EnvType.CLIENT)
     interface RenderModifyPosition {
+        /**
+         * Event to manipulate the position of the tooltip.
+         *
+         * @param matrices The pose stack.
+         * @param context  The current position context.
+         */
         void renderTooltip(PoseStack matrices, PositionContext context);
     }
     
     @Environment(EnvType.CLIENT)
     interface RenderModifyColor {
+        /**
+         * Event to manipulate the color of the tooltip.
+         *
+         * @param matrices The pose stack.
+         * @param x        The x-coordinate of the tooltip.
+         * @param y        The y-coordinate of the tooltip.
+         * @param context  The current color context.
+         */
         void renderTooltip(PoseStack matrices, int x, int y, ColorContext context);
     }
     

common/src/main/java/me/shedaniel/architectury/event/events/client/ClientChatEvent.java

@@ -33,21 +33,38 @@ import java.util.UUID;
 @Environment(EnvType.CLIENT)
 public interface ClientChatEvent {
     /**
-     * Invoked when client tries to send a message, equivalent to forge's {@code ClientChatEvent}.
+     * @see Client#process(String)
      */
     Event<Client> CLIENT = EventFactory.createInteractionResultHolder();
     /**
-     * Invoked when client receives a message, equivalent to forge's {@code ClientChatReceivedEvent}.
+     * @see ClientReceived#process(ChatType, Component, UUID)
      */
     Event<ClientReceived> CLIENT_RECEIVED = EventFactory.createInteractionResultHolder();
     
     @Environment(EnvType.CLIENT)
     interface Client {
+        /**
+         * Event to modify the chat message a clients sends.
+         * Equivalent to Forge's {@code ClientChatEvent} event.
+         *
+         * @param message The raw chat message the client wants to send.
+         * @return Returning {@link InteractionResultHolder#fail(Object)} will result in an empty string being used as message.
+         */
         InteractionResultHolder<String> process(String message);
     }
     
     @Environment(EnvType.CLIENT)
     interface ClientReceived {
+        /**
+         * Event to intercept the receiving of an chat message.
+         * Invoked as soon as the client receives the chat message packet.
+         * Equivalent to Forge's {@code ClientChatReceivedEvent} event.
+         *
+         * @param type    Where was the message emitted from.
+         * @param message The chat message.
+         * @param sender  The packet sender. Can be {@code null}, but probably is the sending player UUID or {@link net.minecraft.Util#NIL_UUID}
+         * @return Returning {@link InteractionResultHolder#fail(Object)} will result in a cancellation of the message and so it is not processed further.
+         */
         InteractionResultHolder<Component> process(ChatType type, Component message, @Nullable UUID sender);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/client/ClientLifecycleEvent.java

@@ -40,9 +40,15 @@ public interface ClientLifecycleEvent {
     @Deprecated
     Event<ClientState> CLIENT_STOPPING = EventFactory.createLoop();
     /**
-     * Invoked after a world is loaded only on client, equivalent to forge's {@code WorldEvent.Load}.
+     * Invoked after a world is loaded only on the client-side.
+     * Equivalent to Forge's {@code WorldEvent.Load} event (on client).
      */
     Event<ClientWorldState> CLIENT_WORLD_LOAD = EventFactory.createLoop();
+    /**
+     * Invoked once client setup has begun.
+     * <p> This happens during {@code FMLClientSetupEvent} on Forge,
+     * or when Architectury API's client entrypoint initialises on Fabric.
+     */
     Event<ClientState> CLIENT_SETUP = EventFactory.createLoop();
     
     @Environment(EnvType.CLIENT)

common/src/main/java/me/shedaniel/architectury/event/events/client/ClientPlayerEvent.java

@@ -28,22 +28,47 @@ import org.jetbrains.annotations.Nullable;
 
 @Environment(EnvType.CLIENT)
 public interface ClientPlayerEvent {
+    /**
+     * @see ClientPlayerJoin#join(LocalPlayer)
+     */
     Event<ClientPlayerJoin> CLIENT_PLAYER_JOIN = EventFactory.createLoop();
+    /**
+     * @see ClientPlayerQuit#quit(LocalPlayer)
+     */
     Event<ClientPlayerQuit> CLIENT_PLAYER_QUIT = EventFactory.createLoop();
+    /**
+     * @see ClientPlayerRespawn#respawn(LocalPlayer, LocalPlayer)
+     */
     Event<ClientPlayerRespawn> CLIENT_PLAYER_RESPAWN = EventFactory.createLoop();
     
     @Environment(EnvType.CLIENT)
     interface ClientPlayerJoin {
+        /**
+         * Invoked whenever a client player joins a level
+         *
+         * @param player The player joining.
+         */
         void join(LocalPlayer player);
     }
     
     @Environment(EnvType.CLIENT)
     interface ClientPlayerQuit {
+        /**
+         * Invoked whenever a client player leaves a level and is cleared on the client side.
+         *
+         * @param player The player leaving.
+         */
         void quit(@Nullable LocalPlayer player);
     }
     
     @Environment(EnvType.CLIENT)
     interface ClientPlayerRespawn {
+        /**
+         * Invoked whenever the player respawn packet is received by the client.
+         *
+         * @param oldPlayer The player before the respawn.
+         * @param newPlayer The player after the respawn.
+         */
         void respawn(LocalPlayer oldPlayer, LocalPlayer newPlayer);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/client/ClientRawInputEvent.java

@@ -29,31 +29,58 @@ import net.minecraft.world.InteractionResult;
 @Environment(EnvType.CLIENT)
 public interface ClientRawInputEvent {
     /**
-     * Invoked after the mouse has scrolled, but doesn't have a screen opened, and in a world, equivalent to forge's {@code InputEvent.MouseScrollEvent}.
+     * @see MouseScrolled#mouseScrolled(Minecraft, double)
      */
     Event<MouseScrolled> MOUSE_SCROLLED = EventFactory.createInteractionResult();
     /**
-     * Invoked after the mouse has clicked, before the screen intercepts, equivalent to forge's {@code InputEvent.RawMouseEvent}.
+     * @see MouseClicked#mouseClicked(Minecraft, int, int, int)
      */
     Event<MouseClicked> MOUSE_CLICKED_PRE = EventFactory.createInteractionResult();
-    /**
-     * Invoked after the mouse has clicked, after the screen intercepts, equivalent to forge's {@code InputEvent.MouseInputEvent}.
-     */
     Event<MouseClicked> MOUSE_CLICKED_POST = EventFactory.createInteractionResult();
     /**
-     * Invoked after a key was pressed, after the screen intercepts, equivalent to forge's {@code InputEvent.KeyInputEvent}.
+     * @see KeyPressed#keyPressed(Minecraft, int, int, int, int)
      */
     Event<KeyPressed> KEY_PRESSED = EventFactory.createInteractionResult();
     
     interface KeyPressed {
+        /**
+         * Invoked whenever a key input is performed.
+         * Equivalent to Forge's {@code InputEvent.KeyInputEvent} event.
+         *
+         * @param client    The Minecraft instance performing it.
+         * @param keyCode   The key code.
+         * @param scanCode  The raw keyboard scan code.
+         * @param action    The action that should be performed.
+         * @param modifiers Additional modifiers.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the key press.
+         */
         InteractionResult keyPressed(Minecraft client, int keyCode, int scanCode, int action, int modifiers);
     }
     
     interface MouseScrolled {
+        /**
+         * Invoked whenever the mouse scroll wheel is used.
+         * Equivalent to Forge's {@code InputEvent.MouseScrollEvent} event.
+         *
+         * @param client The Minecraft instance performing it.
+         * @param amount The amount of movement.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the mouse scroll functions.
+         * At the time this is actually called, any open screen already has processed the scroll movement and so it can't be undone.
+         */
         InteractionResult mouseScrolled(Minecraft client, double amount);
     }
     
     interface MouseClicked {
+        /**
+         * Invoked whenever a mouse button is pressed.
+         * There are two variants, either a raw mouse input or the input after it is processed by the game.
+         *
+         * @param client The Minecraft instance performing it.
+         * @param button The pressed mouse button.
+         * @param action The action that should be performed.
+         * @param mods   Additional modifiers.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the mouse click.
+         */
         InteractionResult mouseClicked(Minecraft client, int button, int action, int mods);
     }
 }

common/src/main/java/me/shedaniel/architectury/event/events/client/ClientScreenInputEvent.java

@@ -29,46 +29,166 @@ import net.minecraft.world.InteractionResult;
 
 @Environment(EnvType.CLIENT)
 public interface ClientScreenInputEvent {
+    /**
+     * @see MouseScrolled#mouseScrolled(Minecraft, Screen, double, double, double)
+     */
     Event<MouseScrolled> MOUSE_SCROLLED_PRE = EventFactory.createInteractionResult();
     Event<MouseScrolled> MOUSE_SCROLLED_POST = EventFactory.createInteractionResult();
+    /**
+     * @see MouseClicked#mouseClicked(Minecraft, Screen, double, double, int)
+     */
     Event<MouseClicked> MOUSE_CLICKED_PRE = EventFactory.createInteractionResult();
     Event<MouseClicked> MOUSE_CLICKED_POST = EventFactory.createInteractionResult();
+    /**
+     * @see MouseReleased#mouseReleased(Minecraft, Screen, double, double, int)
+     */
     Event<MouseReleased> MOUSE_RELEASED_PRE = EventFactory.createInteractionResult();
     Event<MouseReleased> MOUSE_RELEASED_POST = EventFactory.createInteractionResult();
+    /**
+     * @see MouseDragged#mouseDragged(Minecraft, Screen, double, double, int, double, double)
+     */
     Event<MouseDragged> MOUSE_DRAGGED_PRE = EventFactory.createInteractionResult();
     Event<MouseDragged> MOUSE_DRAGGED_POST = EventFactory.createInteractionResult();
+    /**
+     * @see KeyTyped#charTyped(Minecraft, Screen, char, int)
+     */
     Event<KeyTyped> CHAR_TYPED_PRE = EventFactory.createInteractionResult();
     Event<KeyTyped> CHAR_TYPED_POST = EventFactory.createInteractionResult();
+    /**
+     * @see KeyPressed#keyPressed(Minecraft, Screen, int, int, int)
+     */
     Event<KeyPressed> KEY_PRESSED_PRE = EventFactory.createInteractionResult();
     Event<KeyPressed> KEY_PRESSED_POST = EventFactory.createInteractionResult();
+    /**
+     * @see KeyReleased#keyReleased(Minecraft, Screen, int, int, int)
+     */
     Event<KeyReleased> KEY_RELEASED_PRE = EventFactory.createInteractionResult();
     Event<KeyReleased> KEY_RELEASED_POST = EventFactory.createInteractionResult();
     
     interface KeyPressed {
+        /**
+         * Invoked whenever a key press is performed inside a screen.
+         * Equivalent to Forge's {@code GuiScreenEvent.KeyboardKeyPressedEvent} event.
+         *
+         * <p> This event is handled in two phases PRE and POST, which are invoked
+         * before and after the keys have been processed by the screen, respectively.
+         *
+         * @param client    The Minecraft instance performing it.
+         * @param screen    The screen this keystroke was performed in.
+         * @param keyCode   The key code.
+         * @param scanCode  The raw keyboard scan code.
+         * @param modifiers Additional modifiers.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the key press.
+         */
         InteractionResult keyPressed(Minecraft client, Screen screen, int keyCode, int scanCode, int modifiers);
     }
     
     interface KeyReleased {
+        /**
+         * Invoked whenever a held key is released inside a screen.
+         * Equivalent to Forge's {@code GuiScreenEvent.KeyboardKeyReleasedEvent} event.
+         *
+         * <p> This event is handled in two phases PRE and POST, which are invoked
+         * before and after the keys have been processed by the screen, respectively.
+         *
+         * @param client    The Minecraft instance performing it.
+         * @param screen    The screen this keystroke was performed in.
+         * @param keyCode   The key code.
+         * @param scanCode  The raw keyboard scan code.
+         * @param modifiers Additional modifiers.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the key release.
+         */
         InteractionResult keyReleased(Minecraft client, Screen screen, int keyCode, int scanCode, int modifiers);
     }
     
     interface KeyTyped {
+        /**
+         * Invoked whenever a character is typed within a screen.
+         * Equivalent to Forge's {@code GuiScreenEvent.KeyboardCharTypedEvent} event.
+         *
+         * <p> This event is handled in two phases PRE and POST, which are invoked
+         * before and after the keys have been processed by the screen, respectively.
+         *
+         * @param client    The Minecraft instance performing it.
+         * @param screen    The screen this keystroke was performed in.
+         * @param character The typed character.
+         * @param keyCode   The key code.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the key release.
+         */
         InteractionResult charTyped(Minecraft client, Screen screen, char character, int keyCode);
     }
     
     interface MouseScrolled {
+        /**
+         * Invoked whenever the mouse scroll wheel is moved.
+         * Equivalent to Forge's {@code GuiScreenEvent.MouseScrollEvent} event.
+         *
+         * <p> This event is handled in two phases PRE and POST, which are invoked
+         * before and after the keys have been processed by the screen, respectively.
+         *
+         * @param client The Minecraft instance performing it.
+         * @param screen The screen this keystroke was performed in.
+         * @param mouseX The scaled x-coordinate of the mouse cursor.
+         * @param mouseY The scaled y-coordinate of the mouse cursor.
+         * @param amount The amount the scroll wheel is moved.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the key release.
+         */
         InteractionResult mouseScrolled(Minecraft client, Screen screen, double mouseX, double mouseY, double amount);
     }
     
     interface MouseReleased {
+        /**
+         * Invoked whenever a mouse button is released.
+         * Equivalent to Forge's {@code GuiScreenEvent.MouseReleasedEvent} event.
+         *
+         * <p> This event is handled in two phases PRE and POST, which are invoked
+         * before and after the keys have been processed by the screen, respectively.
+         *
+         * @param client The Minecraft instance performing it.
+         * @param screen The screen this keystroke was performed in.
+         * @param mouseX The scaled x-coordinate of the mouse cursor.
+         * @param mouseY The scaled y-coordinate of the mouse cursor.
+         * @param button The released mouse button.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the key release.
+         */
         InteractionResult mouseReleased(Minecraft client, Screen screen, double mouseX, double mouseY, int button);
     }
     
     interface MouseDragged {
+        /**
+         * Invoked whenever the mouse is dragged across a screen.
+         * Equivalent to Forge's {@code GuiScreenEvent.MouseDragEvent} event.
+         *
+         * <p> This event is handled in two phases PRE and POST, which are invoked
+         * before and after the keys have been processed by the screen, respectively.
+         *
+         * @param client  The Minecraft instance performing it.
+         * @param screen  The screen this keystroke was performed in.
+         * @param mouseX1 The initial scaled x-coordinate of the mouse cursor.
+         * @param mouseY1 The initial scaled y-coordinate of the mouse cursor.
+         * @param button  The dragged mouse button.
+         * @param mouseX2 The final scaled x-coordinate of the mouse cursor.
+         * @param mouseY2 The final scaled y-coordinate of the mouse cursor.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the key release.
+         */
         InteractionResult mouseDragged(Minecraft client, Screen screen, double mouseX1, double mouseY1, int button, double mouseX2, double mouseY2);
     }
     
     interface MouseClicked {
+        /**
+         * Invoked whenever a mouse click is performed. A click consists of the press and release of a mouse button.
+         * Equivalent to Forge's {@code GuiScreenEvent.MouseClickedEvent} event.
+         *
+         * <p> This event is handled in two phases PRE and POST, which are invoked
+         * before and after the keys have been processed by the screen, respectively.
+         *
+         * @param client The Minecraft instance performing it.
+         * @param screen The screen this keystroke was performed in.
+         * @param mouseX The scaled x-coordinate of the mouse cursor.
+         * @param mouseY The scaled y-coordinate of the mouse cursor.
+         * @param button The clicked mouse button.
+         * @return Any other result than {@link InteractionResult#PASS} leads to the cancellation of the key release.
+         */
         InteractionResult mouseClicked(Minecraft client, Screen screen, double mouseX, double mouseY, int button);
     }
 }