Adds missing comments and annotations

pom.xml

@@ -82,5 +82,11 @@
             <version>4.8.1</version>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>org.jetbrains</groupId>
+            <artifactId>annotations</artifactId>
+            <version>24.0.1</version>
+            <scope>compile</scope>
+        </dependency>
     </dependencies>
 </project>

src/main/java/net/knarcraft/questmobspawns/QuestMobSpawns.java

@@ -18,6 +18,7 @@ import org.bukkit.entity.EntityType;
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.event.entity.CreatureSpawnEvent;
 import org.bukkit.plugin.java.JavaPlugin;
+import org.jetbrains.annotations.NotNull;
 
 import java.util.ArrayList;
 import java.util.Collection;
@@ -28,6 +29,9 @@ import java.util.Map;
 import java.util.Random;
 import java.util.Set;
 
+/**
+ * This plugin's main class
+ */
 public final class QuestMobSpawns extends JavaPlugin {
 
     private final Random random = new Random();
@@ -41,22 +45,20 @@ public final class QuestMobSpawns extends JavaPlugin {
     @Override
     public void onEnable() {
         plugin = this;
-        // Plugin startup logic
+        // Set up the quests API
         questsAPI = (QuestsAPI) Bukkit.getServer().getPluginManager().getPlugin("Quests");
         if (questsAPI == null) {
+            this.setEnabled(false);
             return;
         }
+
+        // Register listeners
         Bukkit.getPluginManager().registerEvents(new MobDeathListener(), this);
         Bukkit.getPluginManager().registerEvents(new MobBlockDamageListener(questsAPI), this);
 
         Bukkit.getScheduler().scheduleSyncRepeatingTask(this, this::spawnMobs, 200, 30 * 20);
     }
 
-    @Override
-    public void onDisable() {
-        // Plugin shutdown logic
-    }
-
     /**
      * Spawns mobs for all kill areas as necessary
      */
@@ -109,7 +111,16 @@ public final class QuestMobSpawns extends JavaPlugin {
         }
     }
 
-    private void spawnMobsForStage(Map<IStage, Set<IQuester>> questPlayerMap, IQuest quest, IStage stage, int index) {
+    /**
+     * Spawns necessary mobs for a given stage
+     *
+     * @param questPlayerMap <p>The set of quest-takers on the given stage</p>
+     * @param quest          <p>The quest to spawn mobs for</p>
+     * @param stage          <p>The stage to spawn mobs for</p>
+     * @param index          <p>The index of the kill location to spawn mobs for</p>
+     */
+    private void spawnMobsForStage(@NotNull Map<IStage, @NotNull Set<IQuester>> questPlayerMap, @NotNull IQuest quest,
+                                   @NotNull IStage stage, int index) {
         Location killLocation = stage.getLocationsToKillWithin().get(index).clone();
         int radius = stage.getRadiiToKillWithin().get(index);
 
@@ -161,11 +172,11 @@ public final class QuestMobSpawns extends JavaPlugin {
      * Counts the number of entities of the necessary type already in the kill zone
      *
      * @param killLocation <p>The location of the kill location's centre</p>
-     * @param radius <p>The radius of the kill zone</p>
+     * @param radius       <p>The radius of the kill zone</p>
-     * @param entityType <p>The type of entity to kill in the kill zone</p>
+     * @param entityType   <p>The type of entity to kill in the kill zone</p>
      * @return <p></p>
      */
-    private int entitiesInKillZone(Location killLocation, int radius, EntityType entityType) {
+    private int entitiesInKillZone(@NotNull Location killLocation, int radius, @NotNull EntityType entityType) {
         if (killLocation.getWorld() == null) {
             return 0;
         }
@@ -195,8 +206,9 @@ public final class QuestMobSpawns extends JavaPlugin {
      * @param maxMobs        <p>The maximum amount of mobs allowed in the kill zone</p>
      * @return <p>The number of mobs to spawn</p>
      */
-    private int calculateMobNumber(Map<IStage, Set<IQuester>> questPlayerMap, IQuest quest, IStage stage, int index,
+    private int calculateMobNumber(@NotNull Map<IStage, @NotNull Set<IQuester>> questPlayerMap, @NotNull IQuest quest,
-                                   Location killLocation, int radius, int maxMobs) {
+                                   @NotNull IStage stage, int index, @NotNull Location killLocation, int radius,
+                                   int maxMobs) {
         int mobsToSpawn = 0;
         for (IQuester player : questPlayerMap.get(stage)) {
             Location playerLocation = player.getPlayer().getLocation().clone();

src/main/java/net/knarcraft/questmobspawns/listener/MobBlockDamageListener.java

@@ -18,17 +18,22 @@ import org.bukkit.event.entity.EntityDamageByEntityEvent;
 import org.bukkit.event.entity.EntityExplodeEvent;
 import org.bukkit.event.entity.EntityInteractEvent;
 import org.bukkit.event.entity.EntityTargetLivingEntityEvent;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
+/**
+ * A listener for quest mobs causing damage
+ */
 public class MobBlockDamageListener implements Listener {
 
     private final QuestsAPI questsAPI;
 
-    public MobBlockDamageListener(QuestsAPI questsAPI) {
+    public MobBlockDamageListener(@NotNull QuestsAPI questsAPI) {
         this.questsAPI = questsAPI;
     }
 
     @EventHandler(priority = EventPriority.HIGHEST)
-    public void onExplode(EntityExplodeEvent event) {
+    public void onExplode(@NotNull EntityExplodeEvent event) {
         if (QuestMobHelper.isSpawnedMob(event.getEntity())) {
             event.blockList().clear();
             event.setCancelled(false);
@@ -36,17 +41,17 @@ public class MobBlockDamageListener implements Listener {
     }
 
     @EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
-    public void onBlockChange(EntityChangeBlockEvent event) {
+    public void onBlockChange(@NotNull EntityChangeBlockEvent event) {
         cancelIfQuestMob(event, event.getEntity());
     }
 
     @EventHandler
-    public void onDoorBreak(EntityBreakDoorEvent event) {
+    public void onDoorBreak(@NotNull EntityBreakDoorEvent event) {
         cancelIfQuestMob(event, event.getEntity());
     }
 
     @EventHandler
-    public void onEntityTarget(EntityTargetLivingEntityEvent event) {
+    public void onEntityTarget(@NotNull EntityTargetLivingEntityEvent event) {
         Entity entity = event.getEntity();
         if (!QuestMobHelper.isSpawnedMob(entity) || !(event.getTarget() instanceof Player player)) {
             return;
@@ -64,12 +69,12 @@ public class MobBlockDamageListener implements Listener {
     }
 
     @EventHandler
-    public void onTrample(EntityInteractEvent event) {
+    public void onTrample(@NotNull EntityInteractEvent event) {
         cancelIfQuestMob(event, event.getEntity());
     }
 
     @EventHandler(priority = EventPriority.HIGHEST)
-    public void onEntityDamage(EntityDamageByEntityEvent event) {
+    public void onEntityDamage(@NotNull EntityDamageByEntityEvent event) {
         if (!QuestMobHelper.isSpawnedMob(event.getDamager())) {
             return;
         }
@@ -89,21 +94,38 @@ public class MobBlockDamageListener implements Listener {
      * @param player <p>A player</p>
      * @return <p>True if the player has the quest stored in the entity</p>
      */
-    private Boolean hasQuest(Entity entity, Player player) {
+    private Boolean hasQuest(@NotNull Entity entity, @NotNull Player player) {
         IQuester questPlayer = questsAPI.getQuester(player.getUniqueId());
-        IQuest quest = getQuest(QuestMobHelper.getQuestId(entity));
+        String questId = QuestMobHelper.getQuestId(entity);
+        if (questId == null) {
+            return false;
+        }
+        IQuest quest = getQuest(questId);
         if (quest == null) {
             // Remove the entity if the quest it belongs to no longer exists
             entity.remove();
             return false;
         }
-        IStage stage = quest.getStage(QuestMobHelper.getStageId(entity));
+        Integer stageId = QuestMobHelper.getStageId(entity);
-        int index = QuestMobHelper.getIndex(entity);
+        if (stageId == null) {
+            return false;
+        }
+        IStage stage = quest.getStage(stageId);
+        Integer index = QuestMobHelper.getIndex(entity);
+        if (index == null) {
+            return false;
+        }
         return questPlayer.getQuestData().containsKey(quest) && questPlayer.getCurrentStage(quest) == stage &&
                 questPlayer.getQuestData(quest).getMobNumKilled().get(index) < stage.getMobNumToKill().get(index);
     }
 
-    private IQuest getQuest(String questId) {
+    /**
+     * Gets the quest with the given id
+     *
+     * @param questId <p>The id of the quest to get</p>
+     * @return <p>The quest, or null if no such quest exists</p>
+     */
+    private @Nullable IQuest getQuest(@NotNull String questId) {
         for (IQuest quest : questsAPI.getLoadedQuests()) {
             if (quest.getId().equalsIgnoreCase(questId)) {
                 return quest;
@@ -112,7 +134,13 @@ public class MobBlockDamageListener implements Listener {
         return null;
     }
 
-    private void cancelIfQuestMob(Cancellable cancellable, Entity entity) {
+    /**
+     * Cancels a cancellable event if the given entity has been spawned by this plugin
+     *
+     * @param cancellable <p>A cancellable event</p>
+     * @param entity      <p>The entity to check</p>
+     */
+    private void cancelIfQuestMob(@NotNull Cancellable cancellable, @NotNull Entity entity) {
         if (QuestMobHelper.isSpawnedMob(entity)) {
             cancellable.setCancelled(true);
         }

src/main/java/net/knarcraft/questmobspawns/listener/MobDeathListener.java

@@ -6,11 +6,15 @@ import org.bukkit.event.EventPriority;
 import org.bukkit.event.Listener;
 import org.bukkit.event.entity.EntityDeathEvent;
 import org.bukkit.event.entity.EntityDropItemEvent;
+import org.jetbrains.annotations.NotNull;
 
+/**
+ * A listener for the death of quest mobs
+ */
 public class MobDeathListener implements Listener {
 
     @EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
-    public void onMobDeath(EntityDeathEvent deathEvent) {
+    public void onMobDeath(@NotNull EntityDeathEvent deathEvent) {
         if (QuestMobHelper.isSpawnedMob(deathEvent.getEntity())) {
             deathEvent.getDrops().clear();
             deathEvent.setDroppedExp(0);
@@ -18,7 +22,7 @@ public class MobDeathListener implements Listener {
     }
 
     @EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
-    public void onMobDrop(EntityDropItemEvent dropEvent) {
+    public void onMobDrop(@NotNull EntityDropItemEvent dropEvent) {
         if (QuestMobHelper.isSpawnedMob(dropEvent.getEntity())) {
             dropEvent.setCancelled(true);
         }

src/main/java/net/knarcraft/questmobspawns/util/QuestMobHelper.java

@@ -6,7 +6,12 @@ import org.bukkit.NamespacedKey;
 import org.bukkit.entity.Entity;
 import org.bukkit.persistence.PersistentDataContainer;
 import org.bukkit.persistence.PersistentDataType;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
+/**
+ * A helper class for quest mobs
+ */
 public class QuestMobHelper {
 
     private static final NamespacedKey questMobKey = new NamespacedKey(QuestMobSpawns.getPlugin(), "questMob");
@@ -15,23 +20,57 @@ public class QuestMobHelper {
     private static final NamespacedKey mobIndexKey = new NamespacedKey(QuestMobSpawns.getPlugin(), "mobIndex");
     private static final NamespacedKey killZoneLocationKey = new NamespacedKey(QuestMobSpawns.getPlugin(), "killZoneLocationKey");
 
-    public static boolean isSpawnedMob(Entity entity) {
+    /**
+     * Checks whether the given entity has been spawned by this plugin
+     *
+     * @param entity <p>The entity to check</p>
+     * @return <p>True if the entity was spawned by this plugin</p>
+     */
+    public static boolean isSpawnedMob(@NotNull Entity entity) {
         return Boolean.TRUE.equals(entity.getPersistentDataContainer().get(questMobKey, PersistentDataType.BOOLEAN));
     }
 
-    public static void setSpawnedMob(Entity entity) {
+    /**
+     * Marks the given entity as spawned by this plugin
+     *
+     * @param entity <p>The entity to mark</p>
+     */
+    public static void setSpawnedMob(@NotNull Entity entity) {
         entity.getPersistentDataContainer().set(questMobKey, PersistentDataType.BOOLEAN, true);
     }
 
-    public static String getQuestId(Entity entity) {
+    /**
+     * Gets the id of the quest the given entity was spawned for
+     *
+     * @param entity <p>The entity to get the quest id from</p>
+     * @return <p>The quest id, or null if not a quest mob</p>
+     */
+    public static @Nullable String getQuestId(@NotNull Entity entity) {
         return entity.getPersistentDataContainer().get(questIdKey, PersistentDataType.STRING);
     }
 
-    public static Integer getStageId(Entity entity) {
+    /**
+     * Gets the id of the stage the given entity was spawned for
+     *
+     * <p>The stage id is relative to the quest the stage belongs to.</p>
+     *
+     * @param entity <p>The entity to get the stage id for</p>
+     * @return <p>The stage id, or null if not a quest mob</p>
+     */
+    public static @Nullable Integer getStageId(Entity entity) {
         return entity.getPersistentDataContainer().get(stageIdKey, PersistentDataType.INTEGER);
     }
 
-    public static Integer getIndex(Entity entity) {
+    /**
+     * Gets the index of this entity in the quest's "mobs to kill" array
+     *
+     * <p>This property is necessary in order to check whether the player has already reached the required number of
+     * mob kills. This matters if the stage has some other clear property other than killing this type of mob.</p>
+     *
+     * @param entity <p>The entity to check</p>
+     * @return <p>The entity's index, or null if not a quest mob</p>
+     */
+    public static @Nullable Integer getIndex(@NotNull Entity entity) {
         return entity.getPersistentDataContainer().get(mobIndexKey, PersistentDataType.INTEGER);
     }
 
@@ -41,7 +80,7 @@ public class QuestMobHelper {
      * @param entity <p>The entity to get data for</p>
      * @return <p>An array containing x,y,z,radius</p>
      */
-    public static int[] getKillZoneLocation(Entity entity) {
+    public static int[] getKillZoneLocation(@NotNull Entity entity) {
         return entity.getPersistentDataContainer().get(killZoneLocationKey, PersistentDataType.INTEGER_ARRAY);
     }
 
@@ -52,7 +91,8 @@ public class QuestMobHelper {
      * @param questId          <p>The id of the quest the mob was spawned for</p>
      * @param killLocationInfo <p>Information about the kill location (x, y, z, range)</p>
      */
-    public static void setQuestData(Entity entity, String questId, int stageId, int mobIndex, int[] killLocationInfo) {
+    public static void setQuestData(@NotNull Entity entity, @NotNull String questId, int stageId, int mobIndex,
+                                    int[] killLocationInfo) {
         PersistentDataContainer persistentDataContainer = entity.getPersistentDataContainer();
         persistentDataContainer.set(questIdKey, PersistentDataType.STRING, questId);
         persistentDataContainer.set(stageIdKey, PersistentDataType.INTEGER, stageId);
@@ -67,7 +107,7 @@ public class QuestMobHelper {
      * @param location2 <p>The second location</p>
      * @return <p>The 2d distance between the locations</p>
      */
-    public static double get2dDistance(Location location1, Location location2) {
+    public static double get2dDistance(@NotNull Location location1, @NotNull Location location2) {
         return Math.sqrt(Math.pow(location2.getX() - location1.getX(), 2) +
                 Math.pow(location2.getZ() - location1.getZ(), 2));
     }