Added comments for events

README.md

@@ -1,6 +1,7 @@
 # Custom-Fishing
 
 ![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/Xiao-MoMi/Custom-Fishing)
+![Code Size](https://img.shields.io/github/languages/code-size/Xiao-MoMi/Custom-Fishing)
 ![bStats Servers](https://img.shields.io/bstats/servers/16648)
 ![bStats Players](https://img.shields.io/bstats/players/16648)
 ![GitHub](https://img.shields.io/github/license/Xiao-MoMi/Custom-Fishing)

api/src/main/java/net/momirealms/customfishing/api/event/CompetitionEvent.java

@@ -18,26 +18,47 @@
 package net.momirealms.customfishing.api.event;
 
 import net.momirealms.customfishing.api.mechanic.competition.FishingCompetition;
+import net.momirealms.customfishing.api.mechanic.totem.TotemConfig;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * This class represents an event that occurs during a fishing competition.
+ * It is triggered when the state of a fishing competition changes.
+ */
 public class CompetitionEvent extends Event {
 
     private static final HandlerList handlerList = new HandlerList();
     private final State state;
     private final FishingCompetition competition;
 
+    /**
+     * Constructs a new CompetitionEvent.
+     *
+     * @param state The current state of the competition
+     * @param competition The fishing competition associated with this event
+     */
     public CompetitionEvent(State state, FishingCompetition competition) {
         super(true);
         this.state = state;
         this.competition = competition;
     }
 
+    /**
+     * Gets the current {@link State} of the competition.
+     *
+     * @return The current state of the competition
+     */
     public State getState() {
         return state;
     }
 
+    /**
+     * Gets the {@link FishingCompetition} associated with this event.
+     *
+     * @return The fishing competition associated with this event
+     */
     public FishingCompetition getCompetition() {
         return competition;
     }
@@ -52,7 +73,7 @@ public class CompetitionEvent extends Event {
         return getHandlerList();
     }
 
-    public static enum State {
+    public enum State {
         END,
         STOP,
         START

api/src/main/java/net/momirealms/customfishing/api/event/CustomFishingReloadEvent.java

@@ -18,15 +18,24 @@
 package net.momirealms.customfishing.api.event;
 
 import net.momirealms.customfishing.api.BukkitCustomFishingPlugin;
+import net.momirealms.customfishing.api.mechanic.totem.TotemConfig;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * This class represents an event that is triggered when the Custom Fishing plugin is reloaded.
+ */
 public class CustomFishingReloadEvent extends Event {
 
     private static final HandlerList handlerList = new HandlerList();
     private final BukkitCustomFishingPlugin plugin;
 
+    /**
+     * Constructs a new CustomFishingReloadEvent.
+     *
+     * @param plugin The instance of the Custom Fishing plugin that is being reloaded
+     */
     public CustomFishingReloadEvent(BukkitCustomFishingPlugin plugin) {
         this.plugin = plugin;
     }
@@ -41,6 +50,11 @@ public class CustomFishingReloadEvent extends Event {
         return getHandlerList();
     }
 
+    /**
+     * Gets the instance of the {@link BukkitCustomFishingPlugin} that is being reloaded.
+     *
+     * @return The instance of the Custom Fishing plugin
+     */
     public BukkitCustomFishingPlugin getPluginInstance() {
         return plugin;
     }

api/src/main/java/net/momirealms/customfishing/api/event/FishingBagPreCollectEvent.java

@@ -17,6 +17,7 @@
 
 package net.momirealms.customfishing.api.event;
 
+import net.momirealms.customfishing.api.mechanic.totem.TotemConfig;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
@@ -25,6 +26,10 @@ import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * This class represents an event that is triggered before an item is collected into the fishing bag.
+ * It can be cancelled to prevent the item from being collected.
+ */
 public class FishingBagPreCollectEvent extends PlayerEvent implements Cancellable {
 
     private static final HandlerList handlerList = new HandlerList();
@@ -32,6 +37,13 @@ public class FishingBagPreCollectEvent extends PlayerEvent implements Cancellabl
     private boolean isCancelled;
     private final Inventory bag;
 
+    /**
+     * Constructs a new FishingBagPreCollectEvent.
+     *
+     * @param who The player who is collecting the item
+     * @param itemStack The item that is being collected into the fishing bag
+     * @param bag The inventory of the fishing bag
+     */
     public FishingBagPreCollectEvent(@NotNull Player who, ItemStack itemStack, Inventory bag) {
         super(who);
         this.itemStack = itemStack;
@@ -49,6 +61,11 @@ public class FishingBagPreCollectEvent extends PlayerEvent implements Cancellabl
         isCancelled = cancel;
     }
 
+    /**
+     * Gets the {@link ItemStack} that is being collected into the fishing bag.
+     *
+     * @return The item being collected
+     */
     public ItemStack getItemStack() {
         return itemStack;
     }
@@ -62,6 +79,12 @@ public class FishingBagPreCollectEvent extends PlayerEvent implements Cancellabl
         return handlerList;
     }
 
+    /**
+     * Gets the {@link Inventory} of the fishing bag.
+     *
+     * @return The inventory of the fishing bag
+     */
+    @NotNull
     public Inventory getBagInventory() {
         return bag;
     }

api/src/main/java/net/momirealms/customfishing/api/event/FishingHookStateEvent.java

@@ -17,18 +17,30 @@
 
 package net.momirealms.customfishing.api.event;
 
+import net.momirealms.customfishing.api.mechanic.totem.TotemConfig;
 import org.bukkit.entity.FishHook;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * This class represents an event that occurs when the state of a fishing hook changes.
+ * It is triggered by various states of the fishing hook such as when a fish bites, escapes, is lured, or is landed.
+ */
 public class FishingHookStateEvent extends PlayerEvent {
 
     private static final HandlerList handlerList = new HandlerList();
     private final FishHook fishHook;
     private final State state;
 
+    /**
+     * Constructs a new FishingHookStateEvent.
+     *
+     * @param who The player associated with this event
+     * @param hook The fishing hook involved in this event
+     * @param state The state of the fishing hook
+     */
     public FishingHookStateEvent(@NotNull Player who, FishHook hook, State state) {
         super(who);
         this.fishHook = hook;
@@ -39,10 +51,20 @@ public class FishingHookStateEvent extends PlayerEvent {
         return handlerList;
     }
 
+    /**
+     * Gets the {@link FishHook} involved in this event.
+     *
+     * @return The FishHook involved in this event
+     */
     public FishHook getFishHook() {
         return fishHook;
     }
 
+    /**
+     * Gets the {@link State} of the fishing hook.
+     *
+     * @return The state of the fishing hook
+     */
     public State getState() {
         return state;
     }

api/src/main/java/net/momirealms/customfishing/api/event/FishingLootSpawnEvent.java

@@ -19,6 +19,7 @@ package net.momirealms.customfishing.api.event;
 
 import net.momirealms.customfishing.api.mechanic.context.Context;
 import net.momirealms.customfishing.api.mechanic.loot.Loot;
+import net.momirealms.customfishing.api.mechanic.totem.TotemConfig;
 import org.bukkit.Location;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
@@ -27,6 +28,9 @@ import org.bukkit.event.player.PlayerEvent;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * This class represents an event that is triggered when fishing loot is spawned.
+ */
 public class FishingLootSpawnEvent extends PlayerEvent {
 
     private static final HandlerList handlerList = new HandlerList();
@@ -37,6 +41,14 @@ public class FishingLootSpawnEvent extends PlayerEvent {
     private boolean skipActions;
     private boolean summonEntity;
 
+    /**
+     * Constructs a new FishingLootSpawnEvent.
+     *
+     * @param context The context in which the loot is spawned
+     * @param location The location where the loot is spawned
+     * @param loot The loot that is being spawned
+     * @param entity The entity associated with the loot, if any
+     */
     public FishingLootSpawnEvent(@NotNull Context<Player> context, Location location, Loot loot, @Nullable Entity entity) {
         super(context.getHolder());
         this.entity = entity;
@@ -47,41 +59,76 @@ public class FishingLootSpawnEvent extends PlayerEvent {
         this.context = context;
     }
 
+    /**
+     * Gets the {@link Context<Player>} in which the loot is spawned.
+     *
+     * @return The context
+     */
     public Context<Player> getContext() {
         return context;
     }
 
+    /**
+     * Gets the {@link Location} where the loot is spawned.
+     *
+     * @return The location
+     */
     public Location getLocation() {
         return location;
     }
 
     /**
-     * Get the loot entity
+     * Gets the {@link Entity} associated with the loot, if any.
      *
-     * @return entity
+     * @return The entity, or null if the item is `AIR`
      */
     @Nullable
     public Entity getEntity() {
         return entity;
     }
 
+    /**
+     * Gets the {@link Loot} that is being spawned.
+     *
+     * @return The loot
+     */
     @NotNull
     public Loot getLoot() {
         return loot;
     }
 
+    /**
+     * Checks if the entity should be summoned.
+     *
+     * @return True if the entity should be summoned, otherwise false
+     */
     public boolean summonEntity() {
         return summonEntity;
     }
 
+    /**
+     * Sets whether the entity should be summoned.
+     *
+     * @param summonEntity True to summon the entity, otherwise false
+     */
     public void summonEntity(boolean summonEntity) {
         this.summonEntity = summonEntity;
     }
 
+    /**
+     * Checks if actions related to the loot should be skipped.
+     *
+     * @return True if actions should be skipped, otherwise false
+     */
     public boolean skipActions() {
         return skipActions;
     }
 
+    /**
+     * Sets whether actions related to the loot should be skipped.
+     *
+     * @param skipActions True to skip actions, otherwise false
+     */
     public void skipActions(boolean skipActions) {
         this.skipActions = skipActions;
     }

api/src/main/java/net/momirealms/customfishing/api/event/FishingResultEvent.java

@@ -19,6 +19,7 @@ package net.momirealms.customfishing.api.event;
 
 import net.momirealms.customfishing.api.mechanic.context.Context;
 import net.momirealms.customfishing.api.mechanic.context.ContextKeys;
+import net.momirealms.customfishing.api.mechanic.fishing.FishingGears;
 import net.momirealms.customfishing.api.mechanic.loot.Loot;
 import org.bukkit.entity.FishHook;
 import org.bukkit.entity.Player;
@@ -29,6 +30,9 @@ import org.jetbrains.annotations.NotNull;
 
 import java.util.Optional;
 
+/**
+ * This class represents an event that is triggered when a fishing result is determined.
+ */
 public class FishingResultEvent extends PlayerEvent implements Cancellable {
 
     private static final HandlerList handlerList = new HandlerList();
@@ -38,6 +42,14 @@ public class FishingResultEvent extends PlayerEvent implements Cancellable {
     private final FishHook fishHook;
     private Context<Player> context;
 
+    /**
+     * Constructs a new FishingResultEvent.
+     *
+     * @param context The context in which the fishing result occurs
+     * @param result The result of the fishing action
+     * @param fishHook The fish hook involved
+     * @param loot The loot involved
+     */
     public FishingResultEvent(@NotNull Context<Player> context, Result result, FishHook fishHook, Loot loot) {
         super(context.getHolder());
         this.result = result;
@@ -65,26 +77,57 @@ public class FishingResultEvent extends PlayerEvent implements Cancellable {
         isCancelled = cancel;
     }
 
+    /**
+     * Gets the {@link Result} of the fishing action.
+     *
+     * @return The result of the fishing action
+     */
     public Result getResult() {
         return result;
     }
 
+    /**
+     * Gets the {@link FishHook} involved.
+     *
+     * @return The fish hook
+     */
     public FishHook getFishHook() {
         return fishHook;
     }
 
+    /**
+     * Gets the {@link Loot} obtained from the fishing.
+     *
+     * @return The loot
+     */
     public Loot getLoot() {
         return loot;
     }
 
+    /**
+     * Sets the custom score for the fishing action.
+     *
+     * @param score The custom score to set
+     */
     public void setScore(double score) {
         context.arg(ContextKeys.CUSTOM_SCORE, score);
     }
 
+    /**
+     * Gets the {@link Context<Player>}
+     *
+     * @return The context
+     */
     public Context<Player> getContext() {
         return context;
     }
 
+    /**
+     * Gets the amount of loot obtained from the fishing action.
+     * If the result is a failure, the amount is 0.
+     *
+     * @return The amount of loot obtained
+     */
     public int getAmount() {
         if (result == Result.FAILURE) return 0;
         return Optional.ofNullable(context.arg(ContextKeys.AMOUNT)).orElse(1);

api/src/main/java/net/momirealms/customfishing/api/event/RodCastEvent.java

@@ -18,6 +18,7 @@
 package net.momirealms.customfishing.api.event;
 
 import net.momirealms.customfishing.api.mechanic.fishing.FishingGears;
+import org.bukkit.entity.FishHook;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
@@ -34,6 +35,12 @@ public class RodCastEvent extends PlayerEvent implements Cancellable {
     private final PlayerFishEvent event;
     private static final HandlerList handlerList = new HandlerList();
 
+    /**
+     * Constructs a new RodCastEvent.
+     *
+     * @param event The original PlayerFishEvent that triggered this event
+     * @param gears The fishing gears used by the player
+     */
     public RodCastEvent(PlayerFishEvent event, FishingGears gears) {
         super(event.getPlayer());
         this.gears = gears;
@@ -47,7 +54,7 @@ public class RodCastEvent extends PlayerEvent implements Cancellable {
 
     /**
      * Cancelling this event would disable CustomFishing mechanics
-     * If you want to prevent players from casting, use {@link #getBukkitPlayerFishEvent()} instead
+     * If you want to prevent players from casting, cancel {@link #getBukkitPlayerFishEvent()} too
      *
      * @param cancel true if you want to cancel this event
      */
@@ -76,7 +83,7 @@ public class RodCastEvent extends PlayerEvent implements Cancellable {
     }
 
     /**
-     * Gets the original PlayerFishEvent that triggered the {@link RodCastEvent}.
+     * Gets the original {@link PlayerFishEvent} that triggered the {@link RodCastEvent}.
      *
      * @return The original PlayerFishEvent.
      */

api/src/main/java/net/momirealms/customfishing/api/event/TotemActivateEvent.java

@@ -23,6 +23,7 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
+import org.bukkit.event.player.PlayerFishEvent;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -58,7 +59,7 @@ public class TotemActivateEvent extends PlayerEvent implements Cancellable {
     }
 
     /**
-     * Gets the configuration of the totem being activated.
+     * Gets the {@link TotemConfig} of the totem being activated.
      *
      * @return The TotemConfig of the totem being activated.
      */